Subsurface Data Management: Overview of authentication and authorization on AWS implementation of OSDU™ Data Platform
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.
An application makes an HTTP
GET request to
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.
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:
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
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_challengewas specified in the original request) – The base64 URL-encoded representation of the unhashed, random string that was used to generate the
PKCE code_challengein the original request.
- If the client app that was used requires a secret, the
Authorizationheaderfor 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
https://AUTH_DOMAIN/oauth2/token, specifying the
client_idparameters, and setting the
grant_typeparameter to “
expires_in– The length of time (in seconds) that the provided ID and/or access token(s) are valid for.
token_type– Set to “
Example POST request:
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:
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_tokenand makes a call to OAuth
userinfo_endpointand 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
Example user-group mapping DynamoDB records:
User email@example.com is assigned data.default.viewers group with MEMBER role to opendes data partition
User firstname.lastname@example.org is assigned search.service.admin group with OWNER role to opendes data partition
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.