Implementing single sign-on in Assets Server using Amazon Cognito with an external SAML identity provider

Logging in to Assets Server using single sign-on (SSO) via Amazon Cognito is one of the ways of logging in to Assets Server using SSO.

This article describes how to implement Cognito in Assets Server in combination with an external SAML identity provider.

Info: Performing some of the steps described in this article requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or the WoodWing Support team. If your Assets Server is hosted in WoodWing Cloud, you can submit a request and WoodWing will make the necessary change in the Assets Server configuration. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

Notes:  For information about implementing Cognito as the identity provider, see Implementing single sign-on in Assets Server using Amazon Cognito. This article describes setting up Microsoft Entra ID (renamed in 2023 from Microsoft Azure Active Directory) . Other identity providers that support SAML can also be used. When doing so, refer to the documentation of that identity provider. Pay attention to the 'Save' and 'Create' buttons in both Entra ID and Cognito: they are not always clearly visible. Missing one can lead to incorrect settings and thereby an incorrect setup.

Before you start

Before you start, make sure that:

• You have an active Amazon AWS account.
• You have an active Microsoft Entra ID account.
• The Assets Server environment in which Cognito is implemented has a fully working Assets Server and fully working client applications.
• When making use of LDAP, disable it.

Implementation

The implementation consists of the following steps:

1. Setting up Cognito
2. Setting up the external identity provider
3. Setting up Entra ID in Cognito
4. Setting up application roles in Entra ID
5. Configuring Assets Server
6. Setting up permissions in Assets Server
7. Testing the implementation

Info: Use the filter to only show information for one step. All steps 1. Setting up Cognito 2.Setting up the external identity provider 3.Setting up Azure in Cognito 4.Setting up application roles in Azure 5.Configuring Assets Server 6.Setting up permissions in Assets Server 7.Testing the implementation

1. Setting up Cognito

This step consists of creating a user pool and defining a domain name.

Step 1. On the AWS Management Console page, enter Cognito in the Find Services list and click the found result.

The Amazon Cognito page appears.

Step 2. Click Manage User Pools.

The User Pools page appears.

Step 3. In the top right corner, click Create a users pool.

Setting up a users pool involves various steps. Each step has its own page. Refer to the navigation menu on the left side of the page.

• Sign-in options. Select Email and click Next.

• Configure sign-up experience. Use this page to set up how you want your end users to sign in. When done, click Next step.

Notes: We advise to use the option Email address or phone number. Choose one of the available sub options: e-mail addresses, phone numbers, or both. In the section Which standard attributes do you want to require?, select email. In the section Do you want to add custom attributes?, click Add custom attribute to create a custom attribute for storing groups (or roles) from the external identity provider. Use the following values: (Note that these values cannot be changed once the pool has been created. The only way to change them will be to create a new user pool.) Type: string Name: groups Min Length: 1 Max length: 2048 Mutable: select

• Set up the following pages as required:
• Configure security requirements
• Configure message delivery

For more information about these pages, see the Amazon documentation.

• Integrate your app. Add a User pool name and select the Use the Cognito Hosted UI check box. Then select Use a Cognito Domain and add a domain name:

Scroll down and add an App client name. Make sure to select Generate a client secret.

Fill in a callback URL which is the server URL where the Assets Server will be reachable on.

• Review. Review your settings and click Create pool.

2. Setting up the external identity provider

Here, Microsoft Entra ID is used.

Step 1. Open the Entra ID Portal and navigate to Entra ID.

Step 2. Go to Enterprise Applications and choose New application followed by Non-gallery application and give the application a name. Click Add to create the new application.

Step 3. In the newly created App, choose Single sign-on, followed by SAML.

Step 4. Edit the options as follows. When finished, click Save.

• Identifier: The ID of the Cognito user pool. Get this by accessing the General settings of your Cognito user pool. Enter it in the following format:

urn:amazon:cognito:sp:<AWS Cognito user pool ID>

• Reply URL: The Cognito Domain URL. Get this in the Domain name section of your Cognito user pool. Enter it in the following format:

<AWS Cognito Domain URL>/saml2/idpresponse

Step 5. Go to the next step 2 User Attributes & Claims. Add a new claim with the following settings. Leave all other claims as-is. When done, click Save.

• Name: roles
• Namespace: leave empty
• Source attribute: user.assignedroles

Step 6. In the SAML settings, go to step 3 SAML Signing Certificate and click Download for the option Federation Metadata XML. Save the file somewhere on your system, it is needed later in the process.

3. Setting up Entra ID in Cognito

Step 1. In Cognito, go to Federation > Identity Providers > SAML. Upload the previously downloaded XML file and add a name. When done, click Create provider.

Step 2. Click Configure attribute mapping and set up the following configuration. When done click Save changes.

SAML attribute	User pool attribute
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	Email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	Given Name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	Family Name
roles	custom:groups

Step 3. Go to App integration > App client settings and make the following changes. When finished click Save changes.

• Enabled Identity Provider: select Entra ID (the name that was used in step 1).

• Sign in and sign out URLs:
• Callback URL: This URL consists of 2 parts: the URL of Assets Server followed by /openid/callback

Example: https://assets.server.mycompany.com/openid/callback

• Sign out URL: The URL of your Assets Server.

Tip: Concatenate multiple URLs by separating them with a comma.

• OAuth 2.0:
• Allowed OAuth Flows: select Authorization code grant.
• Allowed OAuth Scopes: select all options:
• phone
• email
• openid
• aws.cognito.signin.user.admin
• profile

4. Setting up application roles in Entra ID

Step 1. In Entra ID, go to App registrations, choose the previously created App. In the menu, choose Manifest.

Step 2. In the appRoles section, add the following JSON in the Microsoft Graph App Manifest (New). Verify each property and configure it to your needs. When done, click Save.

Notes: Replace the IDs with random generated GUIDs. Use a Web site such as https://www.guidgenerator.com to generate these. The 'value' property is the name of the group; this same name is later used when setting up groups in Assets Server.

Copy the code

{
    "allowedMemberTypes": [
        "User"
    ],
    "description": "Designers role",
    "displayName": "Designers",
    "id": "YOUR GUID HERE",
    "isEnabled": true,
    "lang": null,
    "origin": "Application",
    "value": "Designers"
},
{
    "allowedMemberTypes": [
        "User"
    ],
    "description": "Editors role",
    "displayName": "Editors",
    "id": "YOUR GUID HERE",
    "isEnabled": true,
    "lang": null,
    "origin": "Application",
    "value": "Editors"
},

Step 3. Assign the role to an Active Directory user or group by doing the following:

Note: When no users exist yet, create these first.

1. Go to Enterprise Applications > your App > Users and groups.
2. Choose Add user/group.
3. Select Users and groups, select one or multiple users or groups and click Select.
4. Click Select Role, select one of the previously created roles and then click Assign.
5. Repeat these steps to assign additional roles.

5. Configuring Assets Server

In Assets Server, a connection to the Assets Server application in Cognito needs to be configured and users who are not part of a group should be prevented from logging in.

Step 1. In Cognito, obtain the needed information by doing the following:

• Under App integration, click Domain name and note down the full Cognito domain name.
• Under General settings, click App clients followed by Show details. Note down the App client id and the App client secret.

Step 2. In the Management Console, access the Single sign-on page and fill in all fields. When done, click Activate in the top right corner.

• SSO provider: Cognito
• Provider URL: the full Cognito domain name.
• Client ID: the Cognito App Client ID.
• Client Secret code: the Cognito App Client Secret.
• Redirect URL: the Assets Server URL.

Examples: Provider URL: https://assets-server-mycompany.auth.eu-west-1.amazoncognito.com Client ID: 4jnjgoe6mrnov1dvq6i1t5060j Client Secret code: 1smtk2spaejt1lh2udi0uesuv73veck4sp3kd6cnhhe7hi57f05v Redirect URL: https://assets-server-mycompany.com

Note: Should you at this stage log out of Assets Server, the activated SSO implementation is in use which is not yet fully operational. To log back in to the Management Console, use the following URL: <your Assets Server URL>/app/#/signin.

Step 3. While still in the Management Console, access the Server configuration > Cluster properties page, search for the following option and set it to true:

• security.login.userTypeRequired

Note: Setting this option to true prevents users who are not part of a group from logging in. When this option is set to false, such users are able to log in which results in a blank page being shown and a license being taken up.

6. Setting up permissions in Assets Server

In Assets Server, a connection to the Assets Server application in Okta needs to be configured and users who are not part of a group should be prevented from logging in.

Step 1. In Assets Server, access the Management Console and open the Permissions > Groups page and assign permissions.

Note: Create groups with the exact same names that were configured as roles in Entra ID (see the 'value' property in the JSON as part of setting up application roles in Entra ID.)

7. Testing the implementation

Test the implementation by logging in to Assets Server using the various applications:

• Assets
• The Brand portal
• The Management Console
• Assets for InDesign

Test the scenario where the user is not yet logged in to Cognito and where the user is already logged in to Cognito. Follow the steps on screen.

Troubleshooting

Error appears when testing the Single Sign-On configuration in Entra ID: "Required String parameter ‘RelayState’ is not present".

This is a known issue but it does not affect the actual working of the integration. Please ignore this error.

Logging in to Assets Server works, but the assigned permissions are not applied.

This is probably caused by the roles that are not correctly passed from Entra ID to Cognito.

Validate this by navigating to the auto-generated user in Cognito: go to Users and groups, select the user and make sure that custom:groups contains the groups (roles) that were assigned in Entra ID.

If the custom:groups property is not shown, validate both Entra ID and Cognito settings. If the issue is not resolved, try re-creating the Cognito User Pool from scratch.

FAQs

Can Entra ID groups be passed instead of creating application roles?

This is possible but not advisable. The reason is that only Entra ID group GUIDs can be passed as SAML attributes. This would result in creating a group named '9cd1c033-efad-4a96-9e8f-1650dc4137b0' in Assets Server instead of 'Designers'.

Are there limitations to the groups mapping, for example the number of groups?

Yes, the total length of the comma-separated custom groups string must not exceed 2048 characters; this is a limitation in Cognito.