Okta

Setting up MIRACL Trust SSO as an Identity Provider within Okta

These instructions are up-to-date at the time of writing, but you should refer back to the official Okta documentation to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

  1. Log in to the Okta management console

  2. Click on ‘Admin’

    click_admin

  3. Click on Security > Identity Providers:

    click_sec_idp

  4. Click on ‘Add Identity Provider’ and fill in the details as below:

    idp_details

    IdP Username and Match against should be set as above, as MIRACL Trust SSO only uses email to identify users

    IdP Issuer URI should be https://<yourssoip>/metadata and IdP Single Sign-On URI should be https://<yourssoip>/sso

    IdP Signature Certificate is your idp.crt public certificate which you will have created as per the instructions in the Installation/Quick Start section of this documentation. Note that this needs to be converted to pem or der format, which can be done with an openssl command such as openssl x509 -in idp.crt -out idp.pem -outform PEM

  5. On returning to the list of IdPs, you can now download Okta’s SP metadata to be added to your IdP config:

    idp_list

  6. As the final step, be sure to click on the settings wheel above in order to specify the newly-configured IdP as the Default:

    default_idp

Configuring your Okta Service Provider profile with MIRACL Trust SSO SAML

  1. Edit /etc/miracl-sso/service_providers/okta.yaml:
sp:
  okta:
    description: Okta
    relay_state: ""
    login_url: https://example-admin.oktapreview.com
    logout_url: https://example.oktapreview.com/login/signout
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: true
    sign_assertion: false
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
  1. Note that sp name is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/okta

  2. login_url is simply the url of your Okta account, while logout_url is the the url of your Okta account with /login/signout appended.

  3. The Okta SP metadata is available via the Okta download metadata link and should be pasted into the above metadata field.

The downloaded metadata file must be converted to a single line with a command such as:

echo -e "\n"$(cat metadata.xml | tr -d '\n')"\n"

The contents will then be output in the terminal in a format that can be pasted into the metadata field.

Note that if you are working with json config files rather than yaml, then once you have downloaded the metadata and saved it as e.g. okta_metadata.xml, it is necessary to convert it to single line format and escape all " characters before copying and pasting it as the above metadata parameter for the Okta SP. This can be done with the following command:

echo -e "\n"$(cat okta_metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"

The contents will then be output in the terminal in a format that can be pasted into the metadata field of a JSON file.

  1. In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:
  • Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
  • Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.

Note that if this is not set correctly, you will receive ‘unauthorized user’ messages.

For more detailed info on using LDAP and regex to control authorized users, please see the LDAP and authorization menu section

  1. Save and close the file.

  2. In your /etc/miracl-sso/config.yaml file make sure you add jivex.yaml to the list of ‘includes’:

includes:
  - core.yaml

# service providers
  - service_providers/okta.yaml
  1. As always after config changes, restart the server with sudo service miracl-sso restart

  2. Now your service is configured, you can visit https://<yourssoip>/login/okta or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Okta login page and SP-initiated login will be triggered automatically.

  3. You will be able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you will be asked to register an email address so as to confirm your identity and register you as a user.