Common Scenarios

Single Sign On (SSO)

16min

When setting up a new SSO integration for an existing or new customer account, follow the User Portal SSO for customer account SSO or the Vendor Platform SSO for the management platform SSO.

Updated SSO Behavior:

  • LicenseSpring now supports a new IdP system, migrating all existing SSO setups and appending the "legacy-" prefix.
  • If you are modifying an existing integration, it is recommended to delete the old setup and configure a new one following the updated documentation.

Key Differences in SSO URLs:

  • Customer Account SSO (for licensing and user portals) uses different URL values from platform SSO.
  • The /api/v4/sso_url endpoint should be used to generate login links dynamically.

Enabling Third-Party Sign-In Integration

Incorporating third-party identity providers (IdPs) for user sign-in is an option within your application. The current support includes social sign-ins via Google and SAML IdPs like Azure Active Directory.

Integrating Social Identity Providers

Before setting up a social IdP, it's necessary to register your application with the respective IdP to acquire a client ID and client secret.

Google

  1. Create a developer account with Google if you haven't already.
  2. Access the OAuth consent screen page.
  3. Opt for the external User Type and proceed to create it.
  4. Provide app information, app domain (optional), and developer contact details.
  5. Save and move forward.
  6. Configure Scopes:
    • Include Scopes like .../auth/userinfo.email, .../auth/userinfo.profile, openid.
  7. Update settings and save.
  8. Continue to Test users settings and save.
  9. Navigate to the Credentials page.
  10. Create credentials > OAuth client ID.
  11. Select web application type, name your OAuth 2.0 client.
  12. Add URIs to authorized JavaScript origins and authorized redirect URIs. Authorized JavaScript origins: https://auth.licensespring.com Authorized redirect URIs: https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
  13. Create and note down your Client ID and your Client Secret.

Incorporating SAML Identity Providers

To enable SAML IdP sign-in for your app users:

  • Follow your SAML identity provider's instructions to add a relying party or application for your SAML 2.0 IdP.
  • Configure the assertion consumer endpoint in your SAML identity provider to:
  • https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
  • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): https://{_domain_name_}.auth.{_region_}.amazoncognito.com/saml2/idpresponse
  • Some SAML IdPs might require the SP urn / Audience URI / SP Entity ID:
    • Use https://auth.licensespring.com/realms/platform
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): urn:amazon:cognito:sp:{_user_pool_id}
  • Configure your SAML IdP to provide an email value (claim) in the SAML assertion.
  • Support SAML 2.0 federation with post-binding endpoints. This ensures direct receipt of SAML responses via a user agent, eliminating the need for retrieval and parsing.

Provide a SAML Provider Name and the metadata document from your SAML IdP.

Azure Active Directory

  1. Access Azure Portal and choose Azure Active Directory.
  2. Add an enterprise application.
  3. Create your own application, input name, and select non-gallery option.
  4. Opt for single sign-on > SAML.
  5. Edit Basic SAML Configuration:
    • Set Identifier as https://auth.licensespring.com/realms/platform
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): urn:amazon:cognito:sp:{_user_pool_id_}
    • Configure Reply URL as https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): https://{_domain_name_}.auth.{_region_}.amazoncognito.com/saml2/idpresponse
  6. Save and close the settings.
  7. Download Federation Metadata XML.
  8. Provide us with your provider's name and the downloaded metadata.

Error: A common Azure DB provider SSO error is shown in the screenshot below:

Azure DB Common Error.
User not assigned to a role for application.


To resolve this error, follow these steps:

  1. In the Azure Active Directory Admin Center, select your app and then search for and select the application to which you want to assign the user account.
  2. In the left pane select Users and Groups and then select Add User/Group.
Assign Users/Groups
Assign Users/Groups

Select Add User/Group
Select Add User/Group


3. On the Add Assignment pane, select None Selected under Users and Groups 4. Search for and select the user that you want to assign to the application, select Select 5. On the Add Assignment, select Assign at the bottom of the pane 6. When all steps are completed, user can normally sign in to account using SSO

Final step to assign user to application
Final step to assign user to application


Auth0

Create an Auth0 Application

  1. Access the Auth0 website dashboard.
  2. Click on Applications, then select Create Application.
  3. In the Create Application dialog box, provide a name for your application (e.g., My App).
  4. Choose Single Page Web Applications as the application type.
  5. Click the Create button.

Create a Test User

  1. Navigate to the left navigation bar and select User Management.
  2. Click on Users.
  3. Choose + Create Your First User. Alternatively, if this is not your initial user, select + Create User.
  4. Within the Create user dialog box, input the user's email and password.
  5. Click the Save button.

Configure SAML Settings

  • Access the left navigation bar and click on Applications.
  • Select the name of the application you previously created.
  • Go to the Addons tab.
  • Activate the SAML2 Web App option.
  • Within the Addon: SAML2 Web App dialog box, navigate to the Settings tab.
  • For the Application Callback URL, input https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
    • Please substitute company code with the appropriate value from platform for your company_code, under platform settings.
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): https://_domain_name_.auth._region_.amazoncognito.com/saml2/idpresponse
  • Under Settings, input the following:
    • No need to add anything, it can be left as is (" {} ").
    • Replace _user_pool_id_ with the value from your SSO settings.
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): { "audience": "urn:amazon:cognito:sp:_user_pool_id_", "mappings": { "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" }, "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" }
  • (Optional) Choose Debug, then log in as the test user you created to confirm that the configuration works.
  • Choose Enable, and then choose Save.

Get the IdP Metadata

  1. In the Addon: SAML2 Web App dialog box, on the Usage tab, find Identity Provider Metadata. Then do either of the following:
  2. Choose download to download the .xml metadata file.

Okta

Create a SAML App

  1. Open the Okta Developer Console.
  2. In the navigation menu, expand Applications, and then choose Applications.
  3. Choose Create App Integration.
  4. In the Create a new app integration menu, choose SAML 2.0 as the Sign-in method.
  5. Choose Next.

Configure SAML Integration

  1. On the Create SAML Integration page, under General Settings, enter a name for your app.
  2. Choose Next.
  3. Under GENERAL, for Single sign on URL, enter https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): https://{domain_name}.auth.{region}.amazoncognito.com/saml2/idpresponse
  4. For Audience URI (SP Entity ID), enter https://auth.licensespring.com/realms/platform/broker/{COMPANY_CODE}/endpoint
    • Existing configs with legacy prefixed (DO NOT USE FOR NEW CONFIGS): urn:amazon:cognito:sp:{user_pool_id}
  5. Under ATTRIBUTE STATEMENTS (OPTIONAL), add a statement with the following information:
    • For Name, enter the SAML attribute name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    • For Value, enter user.email.
  6. For all other settings on the page, leave them as their default values or set them according to your preferences.
  7. Choose Next.
  8. Choose a feedback response for Okta Support.
  9. Choose Finish.

Assign a User

  1. On the Assignments tab for your Okta app, for Assign, choose Assign to People.
  2. Choose Assign next to the user that you want to assign. Note: If this is a new account, the only option available is to choose yourself (the admin) as the user.
  3. (Optional) For User Name, enter a user name, or leave it as the user's email address, if you want.
  4. Choose Save and Go Back. Your user is assigned.
  5. Choose Done.

Get the IdP Metadata

  1. On the Sign On tab for your Okta app, find the Identity Provider metadata hyperlink.
  2. Right-click the hyperlink, and then copy the URL.
    • If not found then click View SAML setup instructions and save the value from Provide the following IDP metadata to your SP provider into an xml file.

Apple

  1. Go to the Apple Developer Console: Visit Apple Developer Console.
  2. Create an Apple Developer Account:
    • If you don't have an Apple Developer account, you will need to create one and enroll in the Apple Developer Program.
  3. Create a New App ID:
    • Navigate to "Certificates, Identifiers & Profiles".
    • Under Identifiers, click the "+" button to create a new App ID.
    • Choose "App IDs" and click "Continue".
    • Enter a description and a bundle ID (e.g., keycloak)
    • Under "Capabilities", enable "Sign in with Apple".
    • Click "Continue" and then "Register".
  4. Create a Service ID:
    • Still under "Identifiers", click the "+" button to create a new Service ID.
    • Select "Service IDs" and click "Continue".
    • Enter a description and an identifier (e.g., keycloak-service)
    • Click "Continue" and then "Register".
    • After creating the Service ID, click on it to edit it.
    • Enable "Sign in with Apple" and configure the redirect URI: https://auth.lcensespring.com/realms/platfrom/broker/{COMPANY_CODE}/endpoint
    • Add the primary App ID created earlier as the Primary App ID.
    • Click "Save".
  5. Create a Key for Apple Sign-In:
    • Navigate to "Keys" and click the "+" button to create a new key.
    • Enable "Sign in with Apple" and click "Configure".
    • Select the Primary App ID and click "Save".
    • Click "Continue" and then "Register".
    • Download the key file it will have a .p8 extension) and save it securely. You will not be able to download it again.
  6. Get Your Team ID and Key ID:
  7. Note down your Team ID from your Apple Developer account.
  8. Note down the Key ID from the key details.
  9. Note down service identifier as mentioned before ins step 4. : keycloak-service
  10. Have your key file ready to upload it on platform.

Setup Apple SSO with above credentials on Licensespring platform.

Frequently Asked Questions

Is there a way for Customer Account SSO to auto-create a LicenseSpring user on login?

Not at the moment. Automatic user creation is only available for platform users.

Can we use the generic OIDC SSO type?

While the generic OIDC type is not exposed in the UI, it can be enabled if necessary. The LicenseSpring SDK already uses OIDC for app-to-IdP communication.

What does "Implemented Keycloak integration in all API endpoints" in v4.0.35 mean?

The IdP system has changed, and all SSO setups have been migrated. If you see unexpected behavior, such as different authentication types being displayed (e.g., OIDC vs. SAML), please send the specific setups to support for verification.

Updated 28 Feb 2025
Doc contributor
Doc contributor
Doc contributor
Doc contributor
Doc contributor
Did this page help you?
PREVIOUS
Changelog
NEXT
Vendor Platform SSO
Docs powered by Archbee