User portal SSO guide
Here is an example of a subdomain for our user portal with a brief explanation of its benefits, how to access it and how to get required data. For more detailed information, you can refer here. Any identity provider for (end-user)user portal SSO login can be configured via our platform under:
Customers-> Customer Accounts -> Single Sign On tab Once any identity provider is configured, users can log in via SSO on our user portal: users.licensespring.com
Users of our Enterprise plan can access the user portal via: {company_code}.users.licensespring.com In this case, it's not necessary to use the company code for login to user portal; only the username and password are required. For SSO login, only the customer account code is needed, as the company code is automatically retrieved.
However, as stated below, during the SSO configuration process, the format required is: company_code-customer_account_code for user portal. Below is a guide on how to set up each identity provider. Note: You can use only one provider at time, if you wish to switch to another, first delete old one then follow our setup guide to add specific new provider.
- Create a New Project:
- Click on the project dropdown at the top left.
- Select "New Project".
- Name your project (e.g., Google) and click "Create".
- Set Up OAuth Consent Screen:
- Navigate to the "OAuth consent screen" tab.
- Select "External" and click "Create".
- Fill in the required fields such as "Application name" and "User support email".
- Configure Scopes: Include Scopes like:
- .../auth/userinfo.email,
- .../auth/userinfo.profile,
- openid
- Continue to Test users settings and save.
- add test users inside the application:
- Create OAuth 2.0 Credentials:
- Go to the "Credentials" tab.
- Click "Create Credentials" and select "OAuth 2.0 Client ID".
- Select "Web application".
- Provide a name for the OAuth client (e.g., MyClient)
- Add <domain> for our platform to Authorized JavaScript origins
- and you can also add here second one but not required to work:
- In the "Authorized redirect URIs" section, add the redirect URL:
- https://<domain>/realms/<realm>/broker/{COMPANY_CODE}-{CUSTOMER_ACCOUNT_CODE}/endpoint
- Click "Create".
- Save Your Credentials:
- Once created, you will be provided with a Client ID and Client Secret.
- Copy and save these credentials. You will need them to configure your application to use Google SSO inside the platform.
If the Account Linking and Verification toggle is ON, then when you create a user, they must verify their email before they can log in. If the toggle is OFF, email verification is not required for the user to log in. Note: redirect_uri is only relevant for applications that use the SDK and allow licensed users to use SSO instead of email/password for authentication. Otherwise, everything else redirects back to the user portal.
- Click on Applications, then select Create Application.
- In the Create Application dialog box, provide a name for your application (e.g., My App).
- Choose Single Page Web Applications as the application type.
- Click the Create button.
Create Test user
- Navigate to the left navigation bar and select User Management.
- Click on Users.
- Choose + Create Your First User. Alternatively, if this is not your initial user, select + Create User.
- Within the Create user dialog box, input the user's email and password.
- 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://<domain>/realms/<realm>/broker/{COMPANY_CODE}-{CUSTOMER_ACCOUNT_CODE}/endpoint
- Please substitute company code and customer account code with the appropriate values from platform for your company_code and customer_account_code, Single Sign-On (SSO) settings.
- Under Settings, input the following and leave it empty: {}
- For minimal Settings to configure email as the NameID, you can use the following configuration:
- { "mappings": { "email": "Email" }, "nameIdentifierProbes": [ "Email" ] }
- (Optional) Choose Debug, then log in as the test user you created to confirm that the
configuration works.
- Choose Enable, and then choose Save.
- In the Addon: SAML2 Web App dialog box, on the Usage tab, find Identity Provider Metadata. Then do either of the following:
- Choose download to download the .xml metadata file.
“
Important: for SAML we use the Name ID format emailaddress.
Upload the downloaded .xml file by choosing SAML for auth0 and confirm to add it.
If the Account Linking and Verification toggle is ON, then when you create a user, they must verify their email before they can log in.
If the toggle is OFF, email verification is not required for the user to log in.
Note: redirect_uri is only relevant for applications that use the SDK and allow licensed users to use SSO instead of email/password for authentication.
Otherwise, everything else redirects back to the user portal.
- In the navigation menu, expand Applications, and then choose Applications.
- Choose Create App Integration.
- In the Create a new app integration menu, choose SAML 2.0 as the Sign-in method.
- Choose Next.
- On the Create SAML Integration page, under General Settings, enter a name for your app.
- Choose Next.
Configure SAML Integration
- Under GENERAL, for Single sign on URL:
- For Audience URI (SP Entity ID), enter:
- For SAML Settings choose if not selected NameID Format EmailAddress - it's located on General tab under the application
- For all other settings on the page, leave them as their default values or set them according to your preferences.
- Choose Next.
- Choose a feedback response for Okta Support.
- Choose Finish.
Assign a User
- On the Assignments tab for your Okta app, for Assign, choose Assign to People.
- 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.
- (Optional) For User Name, enter a user name, or leave it as the user's email address, if you want.
- Choose Save and Go Back. Your user is assigned.
- Choose Done.
Get the IdP Metadata
- On the Sign On tab for your Okta app, find the Identity Provider metadata hyperlink.
- 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.
Important: for SAML we use the Name ID format emailaddress.
Upload the downloaded .xml file by choosing SAML for auth0 and confirm to add it.
If the Account Linking and Verification toggle is ON, then when you create a user, they must verify their email before they can log in.
If the toggle is OFF, email verification is not required for the user to log in.
Note: redirect_uri is only relevant for applications that use the SDK and allow licensed users to use SSO instead of email/password for authentication.
Otherwise, everything else redirects back to the user portal.
- Add an enterprise application.
- Create your own application, input name, and select non-gallery option.
- Opt for single sign-on > SAML.
- Set up single sign on
- Edit Basic SAML Configuration:
- Reply URL (Assertion Consumer Service URL): https://auth.licensespring.com/realms/user-portal/broker/{COMPANY_CODE}-{CUSTOMER_ACCOUNT_CODE}/endpoint
- Save and close the settings.
- Under Attributes & Claims please set if not selected Unique User Identifier(Name ID) to user.mail:
- We are using the email as the NameID. If the UserPrincipalName (UPN) is not the user’s
- primary email in the platform, it should be updated accordingly. This is important as some users may have multiple email aliases, which could result in pulling the incorrect email.
- Download Federation Metadata XML.
- Provide us with your provider's name and the downloaded metadata in .xml format.
Error: A common Azure DB provider SSO error is shown in the screenshot below:
- 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.
- In the left pane select Users and Groups and then 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.
Important: for SAML we use the Name ID format emailaddress.
Upload the downloaded .xml file by choosing SAML for auth0 and confirm to add it.
If the Account Linking and Verification toggle is ON, then when you create a user, they must verify their email before they can log in.
If the toggle is OFF, email verification is not required for the user to log in.
Note: redirect_uri is only relevant for applications that use the SDK and allow licensed users to use SSO instead of email/password for authentication.
Otherwise, everything else redirects back to the user portal.
- 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.
- Create a New App ID:
- 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".
- Enable as a primary App ID on configuration of Sign in with Apple.
- 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 Return URLs to: https://auth.licensespring.com/realms/user-portal/broker/{COMPANY_CODE}-{CUSTOMER_ACCOUNT_CODE}/endpoint
- and add Domains and Subdomains for our platform( without http:// or https://) to:
- Add the primary App ID created earlier as the Primary App ID.
- Click "Save".
- 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.
- Get Your Team ID and Key ID
- Note down your Team ID from your Apple Developer account.
- Note down the Key ID from the key details.
- Note down service identifier as mentioned before in step 4. : keycloak-service
- Have your key file ready to upload it on platform.
Setup Apple SSO with above credentials on Licensespring platform.
Note: When you create new APP ID, it may take up to few hours to apply changes.
If the Account Linking and Verification toggle is ON, then when you create a user, they must verify their email before they can log in. If the toggle is OFF, email verification is not required for the user to log in. Note: redirect_uri is only relevant for applications that use the SDK and allow licensed users to use SSO instead of email/password for authentication. Otherwise, everything else redirects back to the user portal.
