Configuring an external authorization server
The authorization server is the server that is responsible for authenticating and authorizing the client SDKs and Agents.
By default, Session Manager uses the Broker as the authorization server to generate OAuth 2.0 access tokens for client SDKs and software statements for Agents. If you use the Broker as the authorization server, no additional configuration is required.
You can configure Session Manager to use Amazon Cognito as an external authorization server instead of the Broker. For more information, about Amazon Cognito, see the Amazon Cognito Developer Guide.
To use Amazon Cognito as the authorization server
-
Create a new Amazon Cognito user pool. For more information about user pools, see Features of Amazon Cognito in the Amazon Cognito Developer Guide.
Use the create-user-pool command, and specify a pool name and the Region in which to create it.
In this example, we name the pool
dcv-session-manager-client-app
and we create it inus-east-1
.$
aws cognito-idp create-user-pool --pool-namedcv-session-manager-client-app
--regionus-east-1
Example output
{ "UserPoolClient": { "UserPoolId": "us-east-1_QLEXAMPLE", "ClientName": "dcv-session-manager-client-app", "ClientId": "15hhd8jij74hf32f24uEXAMPLE", "LastModifiedDate": 1602510048.054, "CreationDate": 1602510048.054, "RefreshTokenValidity": 30, "AllowedOAuthFlowsUserPoolClient": false } }
Make a note of the
userPoolId
, you'll need it in the next step. -
Create a new domain for your user pool. Use the create-user-pool-domain command, and specify a domain name and the
userPoolId
of the user pool that you created in the previous step.In this example, the domain name is
mydomain-544fa30f-c0e5-4a02-8d2a-a3761EXAMPLE
and we create it inus-east-1
.$
aws cognito-idp create-user-pool-domain --domainmydomain-544fa30f-c0e5-4a02-8d2a-a3761EXAMPLE
--user-pool-idus-east-1_QLEXAMPLE
--regionus-east-1
Example output
{ "DomainDescription": { "UserPoolId": "us-east-1_QLEXAMPLE", "AWSAccountId": "123456789012", "Domain": "mydomain-544fa30f-c0e5-4a02-8d2a-a3761EXAMPLE", "S3Bucket": "aws-cognito-prod-pdx-assets", "CloudFrontDistribution": "dpp0gtexample.cloudfront.net", "Version": "20201012133715", "Status": "ACTIVE", "CustomDomainConfig": {} } }
The format of the user pool domain is as follows:
https://
. In this example, the user pool domain isdomain_name
.auth.region
.amazoncognito.comhttps://mydomain-544fa30f-c0e5-4a02-8d2a-a3761EXAMPLE.auth.us-east-1.amazoncognito.com
. -
Create a user pool client. Use the create-user-pool-client command and specify the
userPoolId
of the user pool that you created, a name for the client, and the Region in which to create it. Also, include the--generate-secret
option to specify that you want to generate a secret for the user pool client being created.In this case, the client name is
dcv-session-manager-client-app
and we create it in theus-east-1
Region.$
aws cognito-idp create-user-pool-client --user-pool-idus-east-1_QLEXAMPLE
--client-namedcv-session-manager-client-app
--generate-secret --regionus-east-1
Example output
{ "UserPoolClient": { "UserPoolId": "us-east-1_QLEXAMPLE", "ClientName": "dcv-session-manager-client-app", "ClientId": "2l9273hp6k2ut5cugg9EXAMPLE", "ClientSecret": "1vp5e8nec7cbf4m9me55mbmht91u61hlh0a78rq1qki1lEXAMPLE", "LastModifiedDate": 1602510291.498, "CreationDate": 1602510291.498, "RefreshTokenValidity": 30, "AllowedOAuthFlowsUserPoolClient": false } }
Note
Make a note of the
ClientId
andClientSecret
. You'll need to provide this information to the developers for when they request access tokens for the API requests. -
Create a new OAuth2.0 resource server for the user pool. A resource server is a server for access-protected resources. It handles authenticated requests for access tokens.
Use the create-resource-server command and specify the
userPoolId
of the user pool, a unique identifier and name for the resource server, the scope, and the Region in which to create it.In this example, we use
dcv-session-manager
as the identifier and the name, and we usesm_scope
as the scope name and description.$
aws cognito-idp create-resource-server --user-pool-idus-east-1_QLEXAMPLE
--identifierdcv-session-manager
--namedcv-session-manager
--scopes ScopeName=sm_scope
,ScopeDescription=sm_scope
--regionus-east-1
Example output
{ "ResourceServer": { "UserPoolId": "us-east-1_QLEXAMPLE", "Identifier": "dcv-session-manager", "Name": "dcv-session-manager", "Scopes": [ { "ScopeName": "sm_scope", "ScopeDescription": "sm_scope" }] } }
-
Update the user pool client.
Use the update-user-pool-client command. Specify the
userPoolId
of the user pool, theClientId
of the user pool client, and the Region. For--allowed-o-auth-flows
, specifyclient_credentials
to indicate that the client should get access tokens from the token endpoint by using a combination of a client ID and a client secret. For--allowed-o-auth-scopes
, specify the resource server identifier and the scope name as follows:
. Include theresource_server_identifier
/scope_name
--allowed-o-auth-flows-user-pool-client
to indicate that the client is allowed to follow the OAuth protocol when interacting with Cognito user pools.$
aws cognito-idp update-user-pool-client --user-pool-idus-east-1_QLEXAMPLE
--client-id2l9273hp6k2ut5cugg9EXAMPLE
--allowed-o-auth-flows client_credentials --allowed-o-auth-scopesdcv-session-manager
/sm_scope
--allowed-o-auth-flows-user-pool-client --regionus-east-1
Example output
{ "UserPoolClient": { "UserPoolId": "us-east-1_QLEXAMPLE", "ClientName": "dcv-session-manager-client-app", "ClientId": "2l9273hp6k2ut5cugg9EXAMPLE", "ClientSecret": "1vp5e8nec7cbf4m9me55mbmht91u61hlh0a78rq1qki1lEXAMPLE", "LastModifiedDate": 1602512103.099, "CreationDate": 1602510291.498, "RefreshTokenValidity": 30, "AllowedOAuthFlows": [ "client_credentials" ], "AllowedOAuthScopes": [ "dcv-session-manager/sm_scope" ], "AllowedOAuthFlowsUserPoolClient": true } }
Note
The user pool is now ready to provide and authenticate access tokens. In this example, the URL for the authorization server is
https://cognito-idp.
.us-east-1
.amazonaws.com/us-east-1_QLEXAMPLE
/.well-known/jwks.json -
Test the configuration.
$
curl -H "Authorization: Basic `echo -n2l9273hp6k2ut5cugg9EXAMPLE
:1vp5e8nec7cbf4m9me55mbmht91u61hlh0a78rq1qki1lEXAMPLE
| base64`" -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://mydomain-544fa30f-c0e5-4a02-8d2a-a3761EXAMPLE
.auth.us-east-1
.amazoncognito.com/oauth2/token?grant_type=client_credentials&scope=dcv-session-manager
/sm_scope
"Example output
{ "access_token":"eyJraWQiOiJGQ0VaRFpJUUptT3NSaW41MmtqaDdEbTZYb0RnSTQ5b2VUT0cxUUI1Q2VJPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIybDkyNzNocDZrMnV0NWN1Z2c5dWg4ZGx0cCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiZGN2LXNlc3Npb24tbWFuYWdlclwvcGVybWlzc2lvbnMiLCJhdXRoX3RpbWUiOjE2MDI1MTMyODMsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbVwvdXMtd2VzdC0yX1FMZTA3SU9GViIsImV4cCI6MTYwMjUxNjg4MywiaWF0IjoxNjAyNTEzMjgzLCJ2ZXJzaW9uIjoyLCJqdGkiOiIyMDk2YTg4NS04YWQ0LTRmYjgtYjI2Mi1hMmNkNDk0OGZjNjYiLCJjbGllbnRfaWQiOiIybDkyNzNocDZrMnV0NWN1Z2c5dWg4ZGx0cCJ9.ZLZpS4CiiLq1X_VSm911hNT4g8A0FKZXScVJyyV0ijcyOfUOBcpgSMGqJagLYORFuYwLS5c7g4eO04wIwnw21ABGIDcOMElDPCJkrzjfLEPS_eyK3dNmlXDEvdS-Zkfi0HIDsd6audjTXKzHlZGScr6ROdZtId5dThkpEZiSx0YwiiWe9crAlqoazlDcCsUJHIXDtgKW64pSj3-uQQGg1Jv_tyVjhrA4JbD0k67WS2V9NW-uZ7t4zwwaUmOi3KzpBMi54fpVgPaewiVlUm_aS4LUFcWT6hVJjiZF7om7984qb2gOa14iZxpXPBJTZX_gtG9EtvnS9uW0QygTJRNgsw", "expires_in":3600, "token_type":"Bearer" }
-
Register the external authorization server for use with the broker by using the register-auth-server command.
$
sudo -u root dcv-session-manager-broker register-auth-server --url https://cognito-idp.us-east-1
.amazonaws.com/us-east-1_QLEXAMPLE
/.well-known/jwks.json
Developers can now use the server to request access tokens. When requesting access tokens, provide the client ID, client secret, and server URL generated here. For more information about requesting access tokens, see Create get an access token and make an API request in theAmazon DCV Session Manager Developer Guide.