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 WoodWing Support team.
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.
Notes:
|
Before you start
Before you start, make sure that:
- You have an active Amazon AWS account.
- You have an active Microsoft Azure 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:

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.
- Name. Enter a pool name and click Step through settings.
- Attributes. Use this page to set up how you want your end users to sign in. When done, click Next step.
Notes:
|
- Set up the following pages as required:
- Policies
- MFA and verifications
- Message customizations
- Tags
- Devices
- Triggers
For more information about these pages, see the Amazon documentation.
- App clients. Click Add an app client, add a name and set the other options to your needs. When done, click Create app client:
- Review. Review your settings and click Create pool.
Step 4. In the menu under App integration, click Domain name and follow the instructions on the page. When done, click Save changes.

Here, Microsoft Azure Active Director is used.
Step 1. Open the Azure Portal and navigate to Azure Active Directory.
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.

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 | |
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 Azure-AD (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 Studio Server followed by /idpcallback.php
Example: https://studio-server.mycompany.com/idpcallback.php
Note: Make sure to check if you are pointing to the directory of Studio Server in your Web server which actually includes the idpcallback.php file.
- Sign out URL: The URL of your Studio 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
- openid
- aws.cognito.signin.user.admin
- profile

Step 1. In Azure, go to App registrations, choose the previously created App. In the menu, choose Manifest.
Step 2. In the appRoles section, add the following JSON. Verify each property and configure it to your needs. When done, click Save.
Notes:
|
{
"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.
- Go to Enterprise Applications > your App > Users and groups.
- Choose Add user.
- Select Users and groups, select one or multiple users or groups and click Select.
- Click Select Role, select one of the previously created roles and then click Assign.
- Repeat these steps to assign additional roles.

In Studio Server, a connection to the Enterprise application in Cognito needs to be configured.
For this, we need information from Cognito.
Step 1. In Cognito, do the following:
- Under General settings, click App clients followed by Show details. Note down the App client id and the App client secret.
Step 2. In Studio Server, add and configure the following settings in the config_overrule.php file:
define( 'OPENID_ISSUER_URL', '' ); define( 'OPENID_CLIENT_ID', '' ); define( 'OPENID_CLIENT_SECRET', '' ); |
- OPENID_ISSUER_URL. The main URL of your Cognito account has a fixed format:
Format: https://cognito-idp.region.amazonaws.com/userPoolId
Example: URL for a user pool with ID 'eu-west-1_utBlcvqFr' in the eu-west-1 region: https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_utBlcvqFr |
- OPENID_CLIENT_ID. The client ID as copied in step 1.
- OPENID_CLIENT_SECRET. The App client secret as copied in step 1
- OPENID_SCOPES. Unlike Okta, Cognito only uses the scopes 'openid profile email'.
Example: To add in your config_overrule.php file: define( 'OPENID_SCOPES', 'openid profile email' ); |

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 Azure: "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 Studio Server works, but the assigned permissions are not applied
This is probably caused by the roles that are not correctly passed from Azure 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 Azure.
If the custom:groups property is not shown, validate both Azure and Cognito settings. If the issue is not resolved, try re-creating the Cognito User Pool from scratch.
FAQs
Can Azure groups be passed instead of creating application roles?
This is possible but not advisable. The reason is that only Azure AD 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
- 18 January 2021: Updated the screenshot in step 2 of section 3 'Setting up Azure in Cognito'.
- 18 January 2021: Updated the callback URL setting of step 3 in section 3 'Setting up Azure in Cognito' so that it matches the example given.
- 18 January 2021: Added a note to the Callback URL setting in step 3 of section 3 'Setting up Azure in Cognito'.
- 18 January 2021: Updated the screenshot in step 3 of section 3 'Setting up Azure in Cognito'.
- 18 January 2021: Updated the example in step 2 of section 5 'Configuring Studio Server'.
- 18 January 2021: Added 'OPENID_SCOPES' to step 2 of section 5 'Configuring Studio Server'.
Comments
Do you have corrections or additional information about this article? Leave a comment!
Do you have a question about what is described in this article? Please contact support here.
2 comments
I think this guide may contains errors. I've followed it *to the letter* and in 3. Setting up Azure in Cognito -> Step 2 I get "The attribute mapping is missing required attributes [preferred_username, locale] (Service: AWSCognitoIdentityProviderService; Status Code: 400; Error Code: InvalidParameterException; Request ID: a0221513-f09b-4cca-8e5b-e44a40cae475; Proxy: null)"
Hi Siebrand,
Thanks for the feedback. I have turned your question into a ticket for our Support team to see what the cause is and how we can update the steps when needed.
They will reply to you via that ticket.
Best regards,
Maarten van Kleinwee
Senior Technical Writer, WoodWing Software
Please sign in to leave a comment.