AR Cloud SSO Integration

Overview

The Keycloak instance bundled with an AR Cloud installation allows integrating an external Identity Provider to support Single Sign-On for its users. This page contains short instructions of the configuration steps needed to prepare such an integration. For details, please refer to the Keycloak documentation.

SAML 2.0

SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal (usually an end user) between a SAML authority, named an Identity Provider, and a SAML consumer, named a Service Provider. Keycloak, in our scenario, acts as the latter.

Different identity solutions might have slightly different names for the fields that need to be copied from Keycloak. In general the process requires to create an application / connection in the identity solution and link it with Keycloak using the following fields:

• The Redirect URI / Assertion Consumer Service (ACS) URL / Application Callback URL / Single Sign On URL - used to send a HTTP POST request with the SAMLResponse after a successful user login using the Identity Provider
• The Service Provider entity ID / SP entity ID / Audience URI / Audience Restriction - restricts the audience to the specified Service Provider configuration (one Service Provider might have multiple Identity Providers configured)
• The SAML entity descriptor / Metadata URL / SAML Metadata URL / Identity Provider Metadata - a link to an XML document with all the information necessary to configure the Identity Provider, e.g. entity ID, signing certificate, URLs of the endpoints, supported attributes

Configuration

To configure a SAML-based identity provider, follow the steps below:

1. Access Keycloak from within the Enterprise Console interface by clicking on Users in the top menu.
2. Log in using the generated credentials for the administrator account. The credentials are provided after a successful installation.
3. Select the magicleap realm from the top-left corner.
4. Click on Identity providers in the left menu.
5. Select SAML v2.0 from the list of supported providers.
6. Enter an Alias for your Identity Provider. Changing this value causes the Redirect URI to change, which requires an update in the configuration of the identity solution.

Okta

Okta documentation

Detailed instructions can be found in the Okta documentation:

Create SAML app integrations

7. Open the admin panel for your Okta instance.

8. Expand Applications in the left menu and click on Applications.

9. Click on the Create App Integration button.

10. Select SAML 2.0 as the Sign-in method and click on Next.

11. Enter an App name and click on Next.

12. Copy the Redirect URI value from Kecyloak and paste it in Okta as Single sign-on URL. The value should be in the following format:

    https://{your-domain}/auth/realms/magicleap/broker/{your-alias}/endpoint`

13. Copy the Service provider entity ID value from Keycloak and paste it in Okta as Audience URI (SP Entity ID).

14. Complete the form with your custom configuration, if needed, and click on Next.

15. Select I'm a software vendor. I'd like to integrate my app with Okta and click on Finish.

16. Copy the generated Metadata URL for the application in Okta and paste it in Keycloak as SAML entity descriptor.

17. After a successful verification of the metadata, the Okta application can be added in Keycloak by clicking on Add.

18. Assign the users you want to have access to Keycloak using the created application in Okta.

Auth0

Auth0 documentation

Detailed instructions can be found in the Auth0 documentation:

Configure Auth0 as SAML Identity Provider

7. Open the admin panel for your Auth0 instance.

8. Expand Applications in the left menu and click on Applications.

9. Click on the Create Application button.

10. Enter a Name, select Regular Web Applications and click on Create.

11. Click on the Settings tab, scroll down and expand Advanced Settings, click on the Endpoints tab and copy the SAML Metadata URL value from the SAML section.

12. Paste the copied URL in Keycloak as SAML entity descriptor.

13. After a successful verification of the metadata, the Auth0 application can be added in Keycloak by clicking on Add.

14. Click on the Addons tab for your application in Auth0, click on SAML2 WEB APP and then on the Settings tab in the popup window.

15. Copy the Redirect URI value from Kecyloak and paste it in Auth0 as Application Callback URL.

16. Copy the Service provider entity ID value from Keycloak and include it in Auth0 under Settings as values for the audience and logout.callback fields in the following format:

    {
      "audience": "https://{your-domain}/auth/realms/magicleap",
      "logout": {
        "callback": "http://{your-domain}/auth/realms/magicleap/broker/{your-alias}/endpoint"
      },
      "nameIdentifierProbes": [
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
      ],
      "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:email"
    }

    The two additional fields are responsible for using the email address as the username in Keycloak instead of the ID autogenerated by Auth0.

17. Click on Enable to save the configuration.

Verification

1. Log out of the Enterprise Console. Underneath the standard Sign In button should be a link to log in with your Identity Provider alias.
2. Use the credentials for one of the users from the Identity Provider.
3. Fill in the required user data in Keycloak to complete the process (this is required if the user does not yet exist in Keycloak and needs to be done only once).

Troubleshooting

1. After providing credentials in the Identity Provider and a redirect back to Keycloak the "Login timeout. Please sign in again." error is shown:
   • The clock is not synchronized between Keycloak and the Identity Provider.
   • Edit your Identity Provided in Keycloak and set the "Allowed clock skew" to a couple of seconds.