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

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 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. Any identity provider that supports SAML 2.0 can be used; when doing so, refer to the documentation of that provider.

Both the AWS and the Microsoft consoles change regularly. Menu names in this article reflect the consoles as of September 2026. Where a label differs, the underlying setting is usually unchanged.

Pay attention to the 'Save', 'Apply', and 'Create' buttons in both consoles: they are not always clearly visible, and missing one leads to an incomplete setup that fails later without an obvious cause.

Before you start

Before you start, make sure that:

You have an active Amazon AWS account with permission to create and configure Cognito user pools.
You have access to the Microsoft Entra admin center with at least the Cloud Application Administrator role, which is required to create app registrations and defining app roles.
The Assets Server environment has a fully working Assets Server and fully working client applications.
LDAP is disabled, when it is in use.

Have the following value to hand, because it is needed in several places:

The Assets Server URL, for example https://assets.mycompany.com. Two values are derived from it:

Callback URL: The Assets Server URL followed by /openid/callback.

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

Sign-out URL: The Assets Server URL itself.

You will also collect three values from Cognito along the way. Note these down as you go:

The user pool ID
The Cognito domain
The app client ID and secret

Implementation

The implementation consists of the following steps:

Creating the Cognito user pool
Collecting the Cognito values needed by Entra ID
Creating the application in Entra ID
Defining application roles in Entra ID
Assigning users to the roles
Configuring SAML single sign-on in Entra ID
Adding Entra ID as an identity provider in Cognito
Configuring the Cognito app client
Configuring Assets Server
Setting up permissions in Assets Server
Testing the implementation

Info: Use the filter to only show information for one step.

1. Creating the Cognito user pool

Step 1. In the AWS Management Console, search for Cognito and open the service. Choose User pools, then Create user pool.

The User Pools section in the AWS Management Console

Step 2. Configure the pool as follows.

Sign-in options. Select Email.

The email option in the Amazon Management Console

Required attributes. Select email.

Custom attributes. Add a custom attribute that will hold the roles received from the identity provider:
Type: String
Name: groups
Min length: 1
Max length: 2048
Mutable: Selected

Warning: Custom attributes cannot be changed or removed after the user pool has been created. If any of these values are incorrect, the only remedy is to create a new user pool. Cognito stores the attribute with a prefix, so it appears elsewhere in the console as custom:groups.

A custom attribute set up in the AWS Management Console

Security requirements and message delivery. Configure as required for your organization. For more information, see the Amazon Cognito documentation.

App client. Enter an app client name and select the option to generate a client secret. Assets Server requires a client secret.

An app client setup in the AWS Management Console

Callback and sign-out URLs. Enter the callback URL and sign-out URL derived from your Assets Server URL, as described in section Before you start.

Tip: Multiple URLs can be entered by separating them with a comma.

Domain. Choose to use a Cognito domain and enter a domain prefix.

Step 3. Review the settings and create the pool.

2. Collecting the Cognito values needed by Entra ID

From the user pool that you have just created, note down:

The user pool ID, shown on the user pool overview page.
The Cognito domain, shown under Domain. This is the full domain.

Example: https://assets-mycompany.auth.eu-west-1.amazoncognito.com.

User pool information in the AWS Management Console

3. Creating the application in Entra ID

Step 1. Open the Microsoft Entra admin center and browse to Entra ID > Enterprise applications.

Step 2. Choose New application, then Create your own application.

Step 3. Give the application a name, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create.

The Create your own application in Cognito

4. Defining application roles in Entra ID

Each role you define here becomes a group in Assets Server, so choose names that match the groups you intend to use.

Step 1. Browse to Entra ID > App registrations and select the application you created.

Note: Roles can also be declared by editing the Microsoft Graph App Manifest directly, by adding entries to the appRoles array. This requires generating a unique GUID for each role and is more error-prone than the App roles interface referenced in the steps below. Use it only if you are defining a large number of roles programmatically.

Step 2. Under Manage, select App roles, then Create app role.

Step 3. Complete the pane as follows and click Apply:

Display name: The name shown in the Entra ID interface, for example 'Designers'.
Allowed member types: Users/Groups.
Value: The role name that is sent to Cognito, for example 'Designers'.
Description: A short description of the role.
Do you want to enable this app role? Selected.

Step 4. Repeat for each role you need, for example 'Editors'.

Note: The Value is what ends up in Assets Server. Later, you create groups in Assets Server with exactly these names.

The Create app role screen in Cognito

5. Assigning users to the roles

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

Step 1. Browse to Entra ID > Enterprise applications and select your application.

Step 2. Under Manage, select Users and groups, then Add user/group.

Step 3. Select one or more users or groups.

Step 4. Select a role and choose Assign.

Step 5. Repeat for each role.

Note: Users who are not assigned a role will be able to authenticate, but will arrive in Assets Server with no group membership. See step 9 Configuring Assets Server for how this is handled.

6. Configuring SAML single sign-on in Entra ID

Step 1. In Enterprise applications, select your application, choose Single sign-on, then SAML.

Step 2. Edit Basic SAML Configuration as follows, then click Save:

Identifier (Entity ID): urn:amazon:cognito:sp:<user pool ID>
Reply URL (Assertion Consumer Service URL): <Cognito domain>/saml2/idpresponse

Both values use the details collected in 2. Collecting the Cognito values needed by Entra ID.

A completed SAML configuration

Step 3. Edit Attributes & Claims and add a new claim with the following settings. Leave the existing claims unchanged. Click Save when done.

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

The Manage claim page filled out in Cognito

Step 4. Under SAML Certificates, download the Federation Metadata XML and save it. It is needed in the next step.

7. Adding Entra ID as an identity provider in Cognito

Step 1. In the Cognito console, open your user pool and choose the Social and external providers menu, then Add an identity provider.

Step 2. Choose SAML.

Step 3. Enter a Provider name. This name appears on the sign-in page and is referenced by the app client, so choose something recognizable such as 'EntraID'.

Step 4. Upload the Federation Metadata XML file downloaded in the previous step.

Step 5. Configure the attribute mapping as follows:

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

Step 6. Save the identity provider.

SAML identity provider configuration and the completed attribute mapping table

Note: The attribute mapping of an existing identity provider can be changed afterwards by opening the provider under Social and external providers and editing Attribute mapping.

8. Configuring the Cognito app client

This step activates the identity provider for your application and grants the app client permission to write the mapped attributes.

Both are required; skipping the second one is the most common cause of a setup that appears to work but grants no permissions.

Step 1. In your user pool, choose App integration and select your app client.

Step 2. Enable the identity provider for the app client. Under the app client's Login pages configuration, click Edit and set:

Identity providers: Select the SAML provider created in the previous step.
Callback URL: The Assets Server URL followed by /openid/callback.
Sign-out URL: The Assets Server URL.
OAuth 2.0 grant types: Authorization code grant.
OpenID Connect scopes: Select:
phone
email
openid
aws.cognito.signin.user.admin
profile

Step 3. Grant write access to the custom attribute. Still on the app client page, find Attribute read and write permissions and click Edit. Select both the read and the write option for custom:groups, as well as for the standard attributes you mapped. Save the changes.

Important: Cognito can only populate an attribute during federated sign-in if the app client has write access to it. Newly created custom attributes have no read or write permission by default. If custom:groups is not writable, the group information from Entra ID is discarded silently: sign-in succeeds, but the user has no permissions in Assets Server.

Attribute read and write permissions page with custom:groups read and write selected

Step 4. If you have more than one app client using this user pool, repeat steps 2 and 3 for each of them.

9. Configuring Assets Server

Step 1. In Cognito, collect the remaining values:

The Cognito domain, under App integration.
The app client ID and app client secret, from the app client page.

The app client page showing client ID and the reveal control for the client secret

Step 2. In the Assets Server Management Console, open the Single sign-on page and complete all fields. Click Activate in the top right corner when done.

SSO provider: Cognito.
Provider URL: The full Cognito domain.
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-mycompany.auth.eu-west-1.amazoncognito.com

Client ID: 4jnjgoe6mrnov1dvq6i1t5060j

Client Secret code: 1smtk2spaejt1lh2udi0uesuv73veck4sp3kd6cnhhe7hi57f05v

Redirect URL: https://assets.mycompany.com

A completed Single Sign-On page in the Management Console of Assets Server

Note: Once SSO is activated, logging out of Assets Server means logging back in through the not-yet-verified SSO configuration. To reach the Management Console directly, use <your Assets Server URL>/app/#/signin.

Step 3. Still in the Management Console, open Server configuration > Cluster properties, find security.login.userTypeRequired, and set it to true.

Note: This prevents users who are not a member of any group from logging in. When set to false, such users can log in, are shown a blank page, and consume a license.

10. Setting up permissions in Assets Server

Step 1. In the Management Console, open Permissions > Groups and create a group for each role defined in Entra ID. Use exactly the names used in the Value field of each app role.

Step 2. Assign permissions to each group.

11. Testing the implementation

Assets
The Brand portal
The Management Console
Assets for InDesign

Test both the scenario where the user is not yet signed in to the identity provider and the scenario where the user is already signed in.

Verify that the user receives the permissions belonging to their assigned role. If they do not, see the troubleshooting section below.

Troubleshooting

Sign-in succeeds, but no permissions are applied

Work through these in order:

Check the app client's write permission. In Cognito, open App integration, select the app client, and check Attribute read and write permissions. The custom:groups attribute must have write access. Without it, Cognito discards the incoming group values. This is the most frequent cause.

Check what arrived in Cognito. Open User management > Users, select the automatically created user, and check whether custom:groups contains the roles assigned in Entra ID.

If custom:groups is empty or absent, check the Entra ID side: confirm that the roles claim exists under Attributes & Claims with source attribute user.assignedroles, and confirm that the user actually has a role assigned under Users and groups.

If custom:groups is populated correctly, the problem is on the Assets Server side: check that a group exists with exactly that name under Permissions > Groups, and that it has permissions assigned.

A blank page appears after signing in, and a license is consumed

The user is not a member of any group and security.login.userTypeRequired is set to false. Set it to true, then assign the user a role in Entra ID.

Error when testing the SAML configuration from within Entra ID: 'Required String parameter 'RelayState' is not present'

This is expected when testing from the Entra ID interface and does not affect the working of the integration. Test by signing in to Assets Server instead.

Federated sign-in fails with an error about a required attribute

If the user pool requires an attribute that the identity provider does not send, Cognito cannot create the user profile. Check which attributes are marked required in the user pool and make sure that each one is either mapped from a SAML claim or not required.

FAQs

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

This is possible but not advisable, because only Entra ID group GUIDs can be passed as SAML attributes. The result would be a group named 9cd1c033-efad-4a96-9e8f-1650dc4137b0 in Assets Server rather than Designers.

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

Yes. The total length of the comma-separated group string cannot exceed 2048 characters. This is a Cognito limitation on the custom attribute.

Can an identity provider other than Entra ID be used?

Yes. Any identity provider supporting SAML 2.0 can be used. The Cognito side of the configuration is identical; the identity provider side differs, so refer to that provider's documentation. What matters is that the provider sends the e-mail, given name, name and surname claims, plus a roles claim containing the group names.

Revisions

14 September 2026: Complete update after a recent verification of the steps.