SSO with Microsoft AzureAD / Entra

SAML

Configuration

1. For a SAML provider setup, create your own Enterprise application under Azure Active Directory and select the option to integrate any other application not found in the gallery.
2. Upon creation, head to the Single sign-on page and select SAML. The SAML configuration will prompt for both an Identifier (Entity ID) and a Reply URL (Assertion Consumer Service URL). Copy the required details from the SSO provider form on the PC Locs Cloud into the respective fields. The other fields can be left as empty.
3. Head to the SAML Signing Certificate section within the same page and copy the App Federation Metadata Url into the Metadata document form field on the PC Locs Cloud. Alternatively, the raw Metadata file can be uploaded instead which can be found in the same section labelled as Federation Metadata XML.
4. User attributes and claims are already set up by default. Edit the section to view claims to map selected attributes on the PC Locs Cloud. Claims can also be managed to map other user attributes such as displayname based on your preference. An example of user attribute mappings on PC Locs Cloud:
   1. Name = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
   2. Email = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   3. Roles = roles
5. Assign users and groups to the SAML enterprise application to grant access to the PC Locs Cloud.

Each assigned user will need to select “Sign in with SSO” and enter the SSO Provider name configured in the PC Locs Cloud, then sign-in with their user principal name.

Assigning custom roles for an SSO user

Before assigning a custom role to an SSO user, app roles will need to be created which can be found via App registrations.

1. Create a new app role within your Enterprise Application (configured above) and set the allowed member types to Users/Groups. The value represents the ID of a role listed in the PC Locs Cloud Roles section located within the accounts page.
2. Go to Enterprise applications and select the application used for PC Locs Cloud.
3. Go to Users and groups, select those that require role assignment.
4. Use the “edit assignment” button to add the roles required.
5. Go to Single sign-on and edit the Attributes & Claims, add a new claim.
6. The claim name should be set to the same value as the Roles attribute map (customizable) in the PC Locs Cloud. The namespace can be ignored.
7. Leave the claim source as Attribute and select user.assignedroles from the source attribute dropdown list.

If an invalid role ID is assigned to a user, the SSO login to the PC Locs Cloud will fail.

If the Roles attribute mapping is not set in PC Locs Cloud, all SSO users will be granted the default Admin role.

Troubleshooting

SAML assertion signature is invalid

Ensure that the Identifier and Reply URL in Azure are unique amongst your list of enterprise applications as these details cannot be shared with other enterprise applications within your active directory.

Other issues signing in after entering the provider name

Given that the instructions above are followed and the solutions suggested here do not resolve any of your issues, please contact support for assistance.

OIDC

Configuration

1. For an OIDC provider setup, create a new App registration application under Azure Active Directory. On the register form, copy the callback URL from the SSO provider form on the PC Locs Cloud into the Redirect URI field. Leave the application type as Web as Single-page application is not supported.
2. Once created, copy the Application client ID into the client ID field of the SSO provider form.
3. Create a new client secret and set an expiry based on your preference. Copy the value into the client secret of the SSO provider form. Please note that the secret will have to be regenerated after it expires to persist SSO user access.
4. Use any of the following issuers as the domain with the Directory tenant ID of the OIDC application. The issuer to use can be verified by checking the OpenID Connect metadata document under Endpoints.
   • https://login.microsoftonline.com/{tenantID}/v2.0
   • https://sts.windows.net/{tenantID}
5. After the OIDC SSO provider has been configured on both PC Locs Cloud and Microsoft Azure, users in the SSO directory will now be able to sign-in with their full user principal name. However, owners of the OIDC application cannot sign-in with SSO.

Attribute mappings

• Authorising the profile scope will map the name user attribute to the PC Locs Cloud.
• Authorising the email scope will map the email user attribute to the PC Locs Cloud. Under Token configuration of the OIDC application, add an optional email claim with either ID or access token. The API permission for accessing the email address will be delegated automatically upon creation.
• Authorising the roles scope will map the assigned roles to the PC Locs Cloud.

Assigning custom roles for an SSO user

Before assigning a custom role to an SSO user, app roles will need to be created which can be found via App registrations.

1. Create a new app role and set the allowed member types to Users/Groups. The value represents the ID of a role listed in the PC Locs Cloud Roles section located within the accounts page.
2. Go to Enterprise applications and select the application used for PC Locs Cloud.
3. Go to Users and groups, if there are users added already, edit the selected user(s) and select a role.
4. Users who login to the PC Locs Cloud will be granted limited access based on the permissions set for the assigned role.

If an invalid role ID is assigned to a user, the SSO login to the PC Locs Cloud will fail.

If the roles scopes is not authorised, all SSO users will be granted the default Admin role.

Troubleshooting

User email address is not mapped after authorising scope and adding optional claims

Given the ID or access token type is selected for the claim, ensure the email claim is selected and not any of the verified emails. This may take a few moments before the PC Locs Cloud registers the email attribute on user sign-in.

Issues signing in after entering the provider name

In most cases, this error occurs when there is a misconfiguration in the setup process. Try any of the following solutions and if the problem persists, please contact support for further assistance:

Use the alternate issuer as the domain if there are problems with the first option.

Ensure the user principal name is used on the Microsoft sign-in page. This can be verified by viewing the user details within the provider's user directory.

The OIDC application type has to be web as other types are unsupported.

Ensure a valid client secret is set for the SSO provider in the PC Locs Cloud.

First name and last name

These user attributes are no longer supported for an OIDC provider in the PC Locs Cloud. SAML is the preferred option if name is not mapped for OIDC.