Subsurface Data Management: Overview of authentication and authorization on AWS implementation of OSDU™ Data Platform

Introduction

This blog explains Authentication and Authorization, and how it enables users to use the OSDU Entitlements API to authorize the Service/Data access to the OSDU Platform. Together, these steps enable users to securely access their subsurface data in their AWS implementation of OSDU™ Data Platform environment. This is the third blog post in a series that provides support for getting started with your AWS implementation of OSDU™ Data Platform environment.

Authentication on AWS implementation of OSDU™ Data Platform

Amazon Cognito is a fully managed AWS service that lets you add user sign-up, sign-in, and access control to your web and mobile apps quickly and easily. Amazon Cognito scales to millions of users and supports sign-in with social identity providers, such as Facebook, Google, Amazon, and enterprise identity providers via SAML 2.0.

AWS implementation of OSDU™ Data Platform by default uses Amazon Cognito as an identity provider (IdP). Customers can federate their own enterprise identity provider like Microsoft AD, Okta IdP, and more with Amazon Cognito. There is also an option to completely replace Amazon Cognito and bring in your own OAuth compliant IdP. This will be discussed in a future blog post.

A user pool is a user directory in Amazon Cognito. Amazon Cognito user Pool manages the overhead of handling the tokens that are returned from OpenID Connect (OIDC) and SAML IdP’s. As per OSDU specification, the standard way to authenticate users of the platform is to implement “authorization code grant flow” based on OAuth2.0 and OIDC standards.

Authorization code grant flow

Amazon Cognito user pool supports Authorization Code Grant Flow. The authorization code grant, also known as 3-legged OAuth, is a standard method for authorizing end users. Instead of directly providing user pool tokens to an end user upon authentication, an authorization code is provided. This code is then sent to a custom application that can exchange it for the desired JWT tokens. Because the tokens are never exposed directly to an end user, they are less likely to become compromised. The following diagram illustrates the 3-legged OAuth flow for accessing OSDU APIs.

Step 1:

An application makes an HTTP GET request to https://AUTH_DOMAIN/oauth2/authorize, where AUTH_DOMAIN represents the Amazon Cognito user pool’s configured domain. This request includes the following query parameters:

- response_type – Set to “code” for this grant type.
- client_id – The ID for the desired user pool app client.
- redirect_uri – The URL that a user is directed to after successful authentication.
- state (optional but recommended) – A random value that’s used to prevent cross-site request forgery (CSRF) attacks.
- scope (optional) – A space-separated list of scopes to request for the generated tokens.
  - openid
  - email

After Amazon Cognito verifies the user pool credentials it receives, the user is redirected to the URL that was specified in the original redirect_uri query parameter. The redirect also sets a code query parameter that specifies the authorization code that was vended to the user by Amazon Cognito.

Example GET request:

curl --location --request GET 'https://osduXXXXXXX.auth.us-east-1.amazoncognito.com/oauth2/authorize?client_id=4k309fka575v062qfr7XXXXXX&response_type=code&scope=email+openid&redirect_uri=http://localhost:3000/'

Step 2:

The custom application that’s hosted at the redirect URL can then extract the authorization code from the query parameters and exchange it for user pool tokens. The exchange occurs by submitting a POST request to https://AUTH_DOMAIN/oauth2/token with the following application/x-www-form-urlencoded parameters:

grant_type – Set to “authorization_code” for this grant.
code – The authorization code that’s vended to the user.
client_id – Same as from the request in step 1.
redirect_uri – Same as from the request in step 1.
code_verifier (optional, is required if a code_challenge was specified in the original request) – The base64 URL-encoded representation of the unhashed, random string that was used to generate the PKCE code_challenge in the original request.
If the client app that was used requires a secret, the Authorizationheader for this request is set as “Basic BASE64(CLIENT_ID:CLIENT_SECRET)”, where BASE64(CLIENT_ID:CLIENT_SECRET) is the base64 representation of the app client ID and app client secret, concatenated with a colon.

The JSON returned in the resulting response has the following keys:

id_token – A valid user pool ID token.
access_token – A valid user pool access token.
refresh_token – A valid user pool refresh token. This can be used to retrieve new tokens by sending it through a POST request to https://AUTH_DOMAIN/oauth2/token, specifying the refresh_token and client_id parameters, and setting the grant_type parameter to “refresh_token”.
expires_in – The length of time (in seconds) that the provided ID and/or access token(s) are valid for.
token_type – Set to “Bearer”.

Example POST request:

curl --location --request POST 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_iQhXXXXX/token?grant_type=authorization_code&code=65da52d0-15bd-4c93-bac4-6XXXXX&redirect_uri=http://localhost' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic XXXX6MXNobGg2YmxkYmg1dHBrazhucmkyaW4xdWJlNTluaXRzaTE0ZTRqdmY2MDJ2NXM1cGQ5Ng=='

Step 3:

After an access_token is obtained, it can now be used by your application to make calls to the protected OSDU API endpoints.

Example Decoded payload of an access_token:

 {
  "sub": "723c2c8c-6d5b-485a-bc55-0212df378dcf",
  "event_id": "1765943a-3e01-4225-9785-a0aedd5ee258",
  "token_use": "access",
  "scope": "openid email",
  "auth_time": 1600998xxx,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXX",
  "exp": 1601002xxx,
  "iat": 1600998xxx,
  "version": 2,
  "jti": "f79476b4-c717-46ce-80d7-ac8fa1ba5835",
  "client_id": "771j67to6eolg7xxxxxxxxx",
  "username": "admin@testing.com"
}

Authorization/Entitlements service on AWS implementation of OSDU™ Data Platform

The OSDU Entitlements service is used to enable authorization in AWS implementation of OSDU™ Data Platform. The Entitlements service manages permissions for access to OSDU services and data using groups. A group name defines a permission. There are two types of groups in AWS implementation of OSDU™ Data Platform:

Data groups, which are added to the metadata of data records are used for data authorization, for example default.viewer, data.default.owner
Service groups, which are added to the OSDU Services are used for service authorization, for example storage.user, service.storage.admin

For each group, you can either be added as an OWNER role or a MEMBER role. The only difference is if you are added to OWNER role of a group, then you can manage the members of that group. The Entitlements service uses Amazon DynamoDB to store user-group mapping records for authorization.

The following diagram illustrates the AWS implementation of OSDU™ Data Platform Entitlements service flow.

User sends request to any OSDU API endpoint with access_token in authorization header
OSDU API Endpoint passes the request to the OSDU Service.
OSDU Service decodes the JWT access_token and makes a call to OAuth userinfo_endpoint and extracts the email field and invokes Entitlements service.
Entitlement Service queries the DynamoDB for user-group mapping records.
DynamoDB returns the user-group mapping records to Entitlements Service.
Entitlement Service returns the user-group mapping records to OSDU Service
Based on the user-group mapping records returned by the Entitlement service the user is allowed or denied the request to OSDU API endpoint.
Results are returned as response to the user.

Example POST request to OSDU Search API

curl --location 
--request POST 'https://XXXXXXXXX.execute-api.us-east-1.amazonaws.com/api/search/v2/query' \
--header 'Content-Type: application/json' \
--header 'data-partition-id: opendes' \
--header 'Authorization: Bearer eyJraWQiOiJvQ0l2Y2FFdCt************' \
--data-raw '{"kind": "opendes:osdu:filesfdds:0.2.0"}'

Example user-group mapping DynamoDB records:

User admin@testing.com is assigned data.default.viewers group with MEMBER role to opendes data partition

{
  "dataPartitionId": "opendes",
  "groupDescription": "Viewers group for Default Data Records",
  "groupEmail": "data.default.viewers@opendes.testing.com",
  "groupName": "data.default.viewers",
  "groupUniqueIdentifier": "opendes:data.default.viewers@opendes.testing.com:admin@testing.com",
  "memberEmail": "admin@testing.com",
  "memberEmailAndDataPartition": "admin@testing.com:opendes",
  "role": "MEMBER"
}

User admin@testing.com is assigned search.service.admin group with OWNER role to opendes data partition

{
  "dataPartitionId": "opendes",
  "groupDescription": "Admin Group for AWS implementation of OSDU™ Data Platform Search Service",
  "groupEmail": "service.search.admin@opendes.testing.com",
  "groupName": "service.search.admin",
  "groupUniqueIdentifier": "opendes:service.search.admin@opendes.testing.com:admin@testing.com",
  "memberEmail": "admin@testing.com",
  "memberEmailAndDataPartition": "admin@testing.com:opendes",
  "role": "OWNER"
}

Conclusion

This concludes the blog on Overview of Authentication and Authorization on AWS implementation of OSDU™ Data Platform. In the next blog, we will demonstrate how to consume data from your AWS implementation of OSDU™ Data Platform sandbox. To learn more about how you can transform the core and build the future of your energy business, see AWS Energy.