Difference between revisions of "OIDC SSO Amazon Cognito Testing Steps"

Latest revision as of 05:00, 21 August 2025

Create user pool

Amazon Cognito https://console.aws.amazon.com/cognito/home > User pools > Create user pool

Step 1: Select Cognito user pool provider type

IMPORTANT NOTES:

if you are planning to use EMail authentication with iDempiere then select EMail as the ONLY attribute for sign in, otherwise you won't be able to create your users based on emails
if you are planning to use Name as authentication you can select both User Name + EMail, but make sure that you check "Make user case sensitive", otherwise you won't be able to create GardenAdmin as user (it will end and gardenadmin and the REST integration won't work)

Step 2: Configure password and authentication policy

===

Step 3: Configure sign-up experience

Step 4: Configure email and SMS delivery

Step 5: Integrate app

Step 5.1: Setup integration with app

Step 5.2: Setup Cognito domain

Step 5.3: Select Confidential client, enter app client name and select Generate a client secret

Step 5.4: Enter callback URLs

Step 5.5: Add ALLOW_USER_PASSWORD_AUTH to Authentication flows

Step 5.6: Add Profile to Open ID Connect scopes

User pool configuration

Step 1: Create user

User pool: GardenWorld > Users > Create user

Notes:

User name = iDempiere user (AD_User.Name)
Email address = iDempiere user (AD_User.EMail)
User has to login for the first time using the temporary password to change new password

Step 2: Create group (Optional)

NOTE this step and the next are optional, not required if you uncheck the "Authorization" flag in the iDempiere "Rest OpenID Connect Service configuration" explaned below.

User pool: GardenWorld > Groups > Create group

Note: Group name = iDempiere role (AD_Role.Name) without space

Step 3: Add user to group

User pool: GardenWorld > Groups > Group: GardenWorldAdmin > Add user to group

Step 4: Get region, User pool ID, Client ID, Client secret, Domain and Allowed callback URLs

Step 4.1: Copy region and User pool ID

User pool: GardenWorld > App integration

Get the region from the Token signing key URL. Token signing key URL format - https://cognito-idp.[region].amazonaws.com/[userPoolId]/.well-known/jwks.json.

Copy the User pool ID

Step 4.2: Copy Client ID and Client secret

User pool: GardenWorld > App integration > App client: iDempiere Web Client

Copy the Client ID and Client secret

Step 4.3: Copy Domain

Note: Cognito domain is required for Authorization Code Grant authorization flow

User pool: GardenWorld > App integration > Domain

Copy Domain

Step 4.4: Copy Allowed callback URLs and Hosted UI link address

Note: Allowed callback URL is required for Authorization Code Grant authorization flow

User pool: GardenWorld > App integration > App client: iDempiere Web Client > Hosted UI

Copy Allowed callback URLs

Right-click on the View Hosted UI button to Copy link address

Step 5: Pre Token Generation Lambda trigger (Optional)

User attributes such as email, phone number etc. are included in the ID Token instead of Access Token.

You have to set up a Pre Token Generation Lambda trigger to add custom claims (such as user email, phone number etc.) to the Access Token. Customization of Access Token requires user to turn on the Advanced security features.

Rest OpenID Connect Service configuration

iDempiere Web Client > Tenant: GardenWorld > Rest OpenID Connect Service

Authority URL format - https://cognito-idp.[region].amazonaws.com/[userPoolId]

Audience - User pool: GardenWorld > App integration > App client: iDempiere Web Client > Client ID

Authorization - when checked the integration will verify the roles vs the groups configured on Cognito, when unchecked the roles assignment is completely managed on iDempiere

Generate Secret Hash

Note: Secret Hash is required for Resource Owner Password Credentials (ROPC) authorization flow

Combine the User name and Client ID into a single string
Hash the combined string using the HMAC-SHA256 algorithm and the client secret as the key
Base64 encode the resulting hash

For example, to generate the hash using a linux CLI:

USERNAME=<cognito user pool username>
CLIENT_ID=<your client_id>
CLIENT_SECRET=<your client secret>
SECRET_HASH=$(echo -n $USERNAME$CLIENT_ID | openssl sha256 -binary -mac HMAC -macopt key:$CLIENT_SECRET | base64)
echo $SECRET_HASH

Alternatively for testing you can use an online generator like this: https://www.devglan.com/online-tools/hmac-sha256-online

Testing using Postman

Import amazon-cognito-oidc-test.postman_collection.json and environment-http---localhost-8080.postman_environment.json to Postman
Set variable value
- cognitoDomain - Get Domain value from User pool configuration > Step 4.3 (for Authorization Code Grant flow only)
- cognitoRegion - Get region value from User pool configuration > Step 4.1
- cognitoClientId - Get Client ID value from User pool configuration > Step 4.1
- cognitoSecret - Get Client secret value from User pool configuration > Step 4.1
- cognitoRedirectUri - Get Allowed callback URL from User pool configuration > Step 4.4 (for Authorization Code Grant flow only)
- cognitoUsername - User name of User pool: GardenWorld > Users > User: GardenAdmin (for Resource Owner Password Credentials flow only)
- cognitoPassword - Password of User pool: GardenWorld > Users > User: GardenAdmin (for Resource Owner Password Credentials flow only)
- cognitoSecretHash - Get the generated secret hash from Generate Secret Hash (for Resource Owner Password Credentials flow only)

Authentication Flow 1: Authorization Code Grant

Step 1: Get New Access Token

At the Authorization tab, click Get New Access Token

Postman Desktop, uncheck Authorize using browser, use https://oauth.pstmn.io/v1/callback for callback url
Postman Web, callback url is fix as https://oauth.pstmn.io/v1/browser-callback
VSCode Postman Extension, callback url is fix as https://oauth.pstmn.io/v1/vscode-callback
Depends on the type of Postman client you are using, add the corresponding callback url to Cognito's allowed callback url list

Step 2: Cognito Login

Get New Access Token will open the login dialog for Cognito

Step 3: Use Token

Upon successful authentication, click Proceed to open the MANAGE ACCESS TOKENS dialog. Click Use Token to use the return access token

After execution of Use Token, Access Token is the current token for Bearer Authorization

Step 4: Send Request

Notes:

X-ID-Role is required if user has more than one role access
X-ID-Organization is required if user + role has more than one organization access

Authentication Flow 2: Resource Owner Password Credentials (ROPC)

For ROPC flow, the access token is not OpenID scope, therefore cannot be used to access the endpoints return from well known configuration URL.

Step 1: Get Token

Step 2: Refresh Token

Step 3.1: Get tax records where C_TaxCategory_ID=107

Notes:

X-ID-IdToken is required if iDempiere is configured to use email to login and email information is not included in the Access Token (for Resource Owner Password Credentials flow only)
X-ID-Role is required if user has more than one role access
X-ID-Organization is required if user + role has more than one organization access

Step 3.2: Get document no and description of the order records

Notes:

X-ID-IdToken is required if iDempiere is configured to use email to login and email information is not included in the Access Token (for Resource Owner Password Credentials flow only)
X-ID-Role is required if user has more than one role access
X-ID-Organization is required if user + role has more than one organization access

@@ Line 1: / Line 1: @@
 == Create user pool ==
-Amazon Cognito <nowiki>https://console.aws.amazon.com/cognito/home</nowiki> > User pools > Create user pool
+Amazon Cognito https://console.aws.amazon.com/cognito/home > User pools > Create user pool
 === Step 1: Select Cognito user pool provider type ===
+'''IMPORTANT NOTES:'''
+* if you are planning to use EMail authentication with iDempiere then select EMail as the '''ONLY''' attribute for sign in, otherwise you won't be able to create your users based on emails
+* if you are planning to use Name as authentication you can select both User Name + EMail, but make sure that you check "Make user case sensitive", otherwise you won't be able to create GardenAdmin as user (it will end and gardenadmin and the REST integration won't work)
 [[File:Amazon Cognito Testing Step 1.png]]
 === Step 2: Configure password and authentication policy ===
+[[File:Amazon Cognito Testing Step 2.png]] ===
-=== [[File:Amazon Cognito Testing Step 2.png]] ===
 === Step 3: Configure sign-up experience ===
@@ Line 49: / Line 53: @@
 [[File:Amazon Cognito Testing User Pool Step 1.png]]
-=== Step 2: Create group ===
+=== Step 2: Create group (Optional) ===
+NOTE this step and the next are optional, not required if you uncheck the "Authorization" flag in the iDempiere "Rest OpenID Connect Service configuration" explaned below.
 User pool: GardenWorld > Groups > Create group
@@ Line 100: / Line 106: @@
 === Step 5: Pre Token Generation Lambda trigger (Optional) ===
-User attributes such as email, phone number etc are included in the ID Token instead of Access Token.
+User attributes such as email, phone number etc. are included in the ID Token instead of Access Token.
-You have to set up a Pre Token Generation Lambda trigger to add custom claims (such as user email, phone number etc) to the Access Token. Customization of Access Token requires user to turn on the Advanced security features.
+You have to set up a Pre Token Generation Lambda trigger to add custom claims (such as user email, phone number etc.) to the Access Token. Customization of Access Token requires user to turn on the Advanced security features.
 == Rest OpenID Connect Service configuration ==
@@ Line 110: / Line 116: @@
 Audience - User pool: GardenWorld > App integration > App client: iDempiere Web Client > Client ID
+Authorization - when checked the integration will verify the roles vs the groups configured on Cognito, when unchecked the roles assignment is completely managed on iDempiere
 [[File:Amazon Cognito Testing Rest OpenID Connect Service.png]]
@@ Line 119: / Line 127: @@
 * Hash the combined string using the HMAC-SHA256 algorithm and the client secret as the key
 * Base64 encode the resulting hash
+For example, to generate the hash using a linux CLI:
+ USERNAME=<cognito user pool username>
+ CLIENT_ID=<your client_id>
+ CLIENT_SECRET=<your client secret>
+ SECRET_HASH=$(echo -n $USERNAME$CLIENT_ID | openssl sha256 -binary -mac HMAC -macopt key:$CLIENT_SECRET | base64)
+ echo $SECRET_HASH
+Alternatively for testing you can use an online generator like this: https://www.devglan.com/online-tools/hmac-sha256-online
 == Testing using Postman ==
@@ Line 133: / Line 150: @@
 ** cognitoSecretHash - Get the generated secret hash from Generate Secret Hash (for Resource Owner Password Credentials flow only)
-=== Step 1: Get and Refresh Token ===
+=== Authentication Flow 1: Authorization Code Grant ===
-There are two authentication flows used to get token and refresh token: Authorization Code Grant and Resource Owner Password Credentials (ROPC).
+===== Step 1: Get New Access Token =====
+At the '''Authorization''' tab, click '''Get New Access Token'''
+# Postman Desktop, uncheck '''Authorize using browser''', use '''https://oauth.pstmn.io/v1/callback''' for callback url
+# Postman Web, callback url is fix as '''https://oauth.pstmn.io/v1/browser-callback'''
+# VSCode Postman Extension, callback url is fix as '''https://oauth.pstmn.io/v1/vscode-callback'''
+# Depends on the type of Postman client you are using, add the corresponding callback url to Cognito's allowed callback url list
+<br/>
+[[File:Postman OAuth2 Get New Access Token.png|400x400px|frameless|Postman OAuth2 Get New Access Token]]
-For ROPC flow, the access token is not openid scope, therefore cannot be used to access the endpoints return from well known configuration url.
+===== Step 2: Cognito Login =====
+'''Get New Access Token''' will open the login dialog for Cognito
-==== Step 1.1: Authorization Code Grant ====
+[[File:Cognito Sign In.png|400x400px|frameless|Cognito Sign In]]
-===== Step 1.1.1: Get Code =====
+===== Step 3: Use Token =====
-Get the Hosted UI link address (i.e. Authorization URL) from User pool configuration > Step 4.4
+Upon successful authentication, click '''Proceed''' to open the '''MANAGE ACCESS TOKENS''' dialog. Click '''Use Token''' to use the return access token
-Authorization URL format - [cognitoDomain]/oauth2/authorize?client_id=[cognitoClientId]&response_type=code&scope=email+openid+profile&redirect_uri=[cognitoRedirectUri]
+[[File:Postman Authorization Use Token.png|400x400px|frameless|Postman Authorization Use Token]]
-When the user accesses the Authorization URL, they will be prompted to log in. After logging in and granting permissions, Cognito will redirect them to the redirect_uri with an authorization code.
+After execution of '''Use Token''', Access Token is the current token for Bearer Authorization
-Redirect format - [cognitoRedirectUri]?code=[authorizationCode]
+[[File:Postman Authorization Current Access Token.png|400x400px|frameless|Postman Authorization Current Access Token]]
-===== Step 1.1.2: Get Token =====
+===== Step 4: Send Request =====
-Enter the [authorizationCode] from Step 1.2.1: Get Code to the code value
+''Notes:''
-[[File:Amazon Cognito Testing Postman Step 1 1 2.png]]
+* ''X-ID-Role is required if user has more than one role access''
+* ''X-ID-Organization is required if user + role has more than one organization access''
+<br/>
+[[File:Postman OAuth2 Send Request.png|400x400px|frameless|Postman OAuth2 Send Request]]
-===== Step 1.1.3: Refresh Token =====
+==== Authentication Flow 2: Resource Owner Password Credentials (ROPC) ====
-[[File:Amazon Cognito Testing Postman Step 1 1 3.png]]
+For ROPC flow, the access token is not OpenID scope, therefore cannot be used to access the endpoints return from well known configuration URL.
-==== Step 1.2: Resource Owner Password Credentials (ROPC) ====
+===== Step 1: Get Token =====
-===== Step 1.2.1: Get Token =====
 [[File:Amazon Cognito Testing Postman Step 1 2 1.png]]
-===== Step 1.2.2: Refresh Token =====
+===== Step 2: Refresh Token =====
 [[File:Amazon Cognito Testing Postman Step 1 2 2.png]]
-=== Step 2: Sample REST requests ===
+===== Step 3.1: Get tax records where C_TaxCategory_ID=107 =====
-==== Step 2.1: Get tax records where C_TaxCategory_ID=107 ====
 ''Notes:''
@@ Line 176: / Line 200: @@
 [[File:Amazon Cognito Testing Postman Step 2 1.png]]
-==== Step 2.2: Get document no and description of the order records ====
+==== Step 3.2: Get document no and description of the order records ====
 ''Notes:''