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

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

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

Info: Performing 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 Studio Server is hosted in WoodWing Cloud, you can submit a request and WoodWing will make the necessary change in the Studio 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.

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 Studio Server environment in which Cognito is implemented has a fully working Studio 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 Studio Server
6. 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 User Pools from the menu on the left.

Step 3. In the top right corner, click Create user pool. Follow the images below as an idea to configure it:

Step 4. To create a custom attribute for storing groups (or roles) from the external identity provider, in the left menu for the newly created user pool, click Sign-up and add the following custom attribute:

• Type: string
• Name: groups
• Min Length: 1
• Max length: 2048
• Mutable: select

Step 5. Set up the rest of the options as required. For more information about these pages, see the Amazon documentation.

Step 6. Prepare information for the Azure setup. In a text editor, note down your values for Identifier (Entity ID) and Reply URL according to the following formats:

• Format for Identifier (Entity ID):
urn:amazon:cognito:sp:<yourUserPoolID>

Example: urn:amazon:cognito:sp:ap-southeast-2_nYYYyyYyYy

• Format for Reply URL:
  https://<yourDomainPrefix>.auth.<aws-region>.amazoncognito.com/saml2/idpresponse

Example: https://example-corp-prd.auth.ap-southeast-2.amazoncognito.com/saml2/idpresponse

Note: The Reply URL is the endpoint where Azure will send SAML assertion to Amazon Cognito during the process of user authentication.

For more information, see Adding SAML Identity Providers to a User Pool in the Amazon Cognito Developer Guide.

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. Click on Add enterprise application followed by Create your own application and give the application a name (leave it to the default, Non-gallery). Click Create to create the new application.

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

Step 4. Edit the options from Basic SAML Configuration as follows. When finished, click Save.

• Identifier (Entity ID): Add the Identifier (Entity ID) from Cognito that was stored as part of the previous step.

• Reply URL: Add the Reply URL from Cognito that was stored as part of the previous step.

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 Social and External Providers > Add Identity Provider > SAML.

Step 2. Add a Provider Name and upload thee Federation Metadata XML file that was downloaded from Azure.

Step 3. Update the Map attributes between your SAML provider and your user pool section and set up the following configuration. When done, click Add identity provider.

Step 4. Go to Applications > App clients, click on the specific App client name and make the following changes in the Login pages tab configuration. When finished, click Save changes.

• Allowed callback URLs: the callback URL that was defined before.
• Default redirect URL: the same value as Allowed callback URLs defined before.
• Allowed sign-out URLs > URL: the URL of your Studio Server.
• Identity providers: The name defined in step 2.
• OAuth 2.0 grant types: select Authorization code grant.
• OpenID Connect scopes: select all options:
• phone
• email
• openid
• aws.cognito.signin.user.admin
• profile

Step 5. Prepare information for the Studio Server setup. In a text editor, note down your values for Client ID and Client secret which can be found under App client information.

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 Microsoft Graph App Manifest (New) tab, add the following JSON under appRoles. Verify each property and configure it to your needs. When done, click Save.

{
    "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 (None selected by default).
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 Studio Server

In Studio Server, a connection to the Enterprise application in Cognito needs to be configured and SSO users need to be mapped to Studio Server user accounts.

1. Configuring a connection to the Enterprise application in Cognito

For this, we use the information that was copied from Cognito.

In Studio Server, add and configure the following settings in the config_overrule.php file:

• OPENID_ISSUER_URL. The main URL of your Cognito account has a fixed format:

Format: https://cognito-idp.region.amazonaws.com/userPoolId

• OPENID_CLIENT_ID. The client ID as copied previously.

• OPENID_CLIENT_SECRET. The App client secret as copied previously.

• OPENID_SCOPES. Unlike Okta, Cognito only uses the scopes 'openid profile email'.

2. Mapping SSO users to Studio Server user accounts

Mapping a Cognito user with the properties for a user in Studio Server is done through the 'OPENID_FIELD_MAPPING' setting in the config_overrule.php file.

The following Studio Server properties can be mapped:

• Name
• FullName
• EmailAddress
• Language
• TrackChangesColor
• Organization
• Location

However, we advise to start with one of the following basic configurations which are certain to work and have often been tested:

Configuration 1

• Name
• FullName
• EmailAddress

define( 'OPENID_FIELD_MAPPING', serialize ( [
        'Name' => 'given_name',
        'FullName' => 'name',
        'EmailAddress' => 'email',
] ) );

Configuration 2

• Name
• FullName
• EmailAddress
• Language

define( 'OPENID_FIELD_MAPPING', serialize ( [
	 'Name' => 'preferred_username',
	 'FullName' => 'name',
	 'EmailAddress' => 'email',
	 'Language' => 'locale',
] ) );

6. Testing the implementation

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

• The Studio Server Maintenance pages
• Studio
• Studio for InDesign and InCopy

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. This error can be ignored.

Logging in to Studio 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 the Entra ID and Cognito settings. If the issue is not resolved, try re-creating the Cognito User Pool from scratch.

Entra ID users are unable to log in to Studio Server or the user field values are incorrectly set during login

This happens when SSO users are not correctly mapped with their Studio Server user accounts.

Users are unable to log in when the login details of a user have changed in Active Directory and/or Entra ID

This happens when details such as username and/or e-mail address have changed after for example a user got married and has taken a new last name, or the e-mail domain has changed.

The following error appears in Studio when the user is correctly updated in Active Directory and Entra ID, but not in Cognito:

Unable to log in to Studio Server. Please contact your system administrator.

Unable to resolve the Identity Provider user to a Studio Server user.

To resolve this, manually edit the user details in Cognito so that they are in sync again with Entra ID and Studio.

This will preserve the user and their preferences.

In case you delete the user in Cognito, you will also create a new user in Studio and the old user will still be present, but the user can log in to Studio again.

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 Studio 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.

Revisions

• 13 May 2026: Updated steps and images where needed.