App registration
To be able to use SSO with Microsoft Entra ID, you must first register a new app. To do this, use the ‘App registrations’ service. A new app can be registered via ‘New registration’.
The new app registration requires a name and details of the supported account types.
Select the type ‘Web’ as the redirection URI and enter the following URI first:
https://<DOMAIN>/signoSignUniversal/auth/callback?client_name=ViewerClient
Replace the placeholder ‘<DOMAIN>’ with the domain under which you operate signoSign/Universal. If you use the ‘web.ssmpublicurl’ property on the signoSign/Universal server, these domains must match.
Please note that Microsoft only allows URIs with valid and verifiable TLS certificates (no self-signed certificates). However, an (unprotected) ‘localhost’ address can also be used for test purposes.
Then confirm your selection with ‘Register’.
Further redirection URIs
Once the app registration has been created, switch to the ‘Authentication’ area.
On the right-hand side, you will see the redirection URI you have just configured. Click on ‘Add URI’ and enter the following additional URI:
https://<DOMAIN>/signoSignUniversal/auth/callback?client_name=PoolClient
Replace the placeholder ‘<DOMAIN>’ with the domain under which you operate signoSign/Universal. If you use the ‘web.ssmpublicurl’ property on the signoSign/Universal server, these domains must match.
Please note again that Microsoft only allows URIs with valid and verifiable TLS certificates (no self-signed certificates). However, an (unprotected) ‘localhost’ address can also be used for test purposes.
Click ‘Save’ to accept the entry.
Optional: access tokens for implicit flows
In the app registration under ‘Authentication’ under ‘Implicit approval and hybrid flows’, the option ‘Access tokens (used for implicit flows)’ can be enabled.
This setting is optional and can be used to authorise yourself to the signoSign/Universal REST API using a specific OpenID Connect flow. It can also be used, for example, if you want to create an access token with OpenID Connect Debugger.
Creation of a secret
In the app registration, switch to the ‘Certificates and secrets’ area. There, click on ‘New secret key’. The key requires a description and a validity period.
The created secret is visible under ‘Value’ after creation.
Please save this value for later use, as it cannot be made visible again!
Configuring the token
The next step is to configure the token, as signoSign/Universal needs to know the user’s email address. To configure the token, switch to the ‘Token configuration’ area within the app registration.
On the right-hand side, select ‘Add optional claim’.
Select ‘Access’ as the ‘Token type’ and activate ‘email’ in the list of claims.
Then confirm your selection with ‘Add’.
The following dialogue appears:
Activate the checkbox ‘Activate Microsoft Graph permission ‘email’ (required for claims to be displayed in the token).’ and then click on ‘Add’.
Make API available
The next step is to configure a user-defined area for the API. To do this, go to the ‘Make an API available’ menu and click on ‘Add area’ on the right. This user-defined area is required so that signoSign/Universal can access the required user information.
An application URI, an area name as well as display names and descriptions must be configured. The content is the responsibility of the administrator and is irrelevant for signoSign/Universal. It also defines who is authorised to release this information. Here it is important that ‘Administrators and users’ is selected.
configure signoSign/Universal roles
signoSign/Universal requires specific user roles that must be linked to the users.
To create the roles, switch to the ‘App roles’ area and click on ‘Create app role’.
The app role requires a display name and the permitted member types. The display name is purely for administrative purposes and is irrelevant for signoSign/Universal. Select ‘Users/Groups’ as the permitted member type so that the role can be linked to users or groups in the next step.
The role of signoSign/Universal must be used as the ‘Value’ for the role. There are currently two roles.
-
ssu-user
-
ssu-admin
The role ‘ssu-user’ must be assigned to every normal user. These users only have access to their own documents and processes. The ‘ssu-admin’ role, on the other hand, has access to all documents and processes of all users.
Assignment of roles
The last step is to assign the created roles to your users or groups.
To do this, switch to ‘Enterprise applications’ and select the created application there.
There, switch to ‘Users and groups’ in the menu.
Via ‘Add user/group’ you can select a user or group and link it to one of the roles created. Please note that the assignment of groups is only available in certain Microsoft Entra ID plans.
The configuration in Microsoft Entra ID is then complete and you can configure the created application in signoSign/Universal.
signoSign/Universal takes over the roles from the claim defined via the setting
auth.oidc.rolesClaim.
Registration only with mapped role (optional)
The following option is optional, but is recommended to simplify error handling.
To ensure that Microsoft Entra ID only allows users with a mapped role to log in, the ‘Assignment required?’ option must be enabled. To do this, go to the ‘Properties’ menu and activate it.
Making the app visible to users
If you want users to see the app within ‘My apps’ in Office 365, you can set the option ‘Visible to users?’ to ‘Yes’.
To access the app, the ‘URL of the start page’ must be set to the URL of the application in the app registration under ‘Branding & Properties’ (e.g. https://YOUR-DOMAIN.COM/signoSignUniversal/pool).