The article discusses how to use AWS services with OutSystems applications without needing to share permanent AWS credentials. It outlines an approach that involves using OutSystems Developer Cloud's identity provider to obtain a user's access token, exchanging that token with AWS Cognito for temporary AWS credentials, and then using those temporary credentials to access AWS services.
💡
Please note that the podcast episode above is automatically generated from this article and may not include a proper level of detail.
Consuming AWS services with OutSystems is easy if you use one of the available AWS Connector libraries on Forge, such as S3, Translate, Rekognition, and others. To use them, you need AWS credentials created by your AWS administrators and given to you. The officially OutSystems supported AWS connectors use permanent, or long-lasting, AWS credentials, which consist of an access key and a secret access key. Some community AWS connectors also support temporary credentials. Additionally, your AWS administrators need to grant permissions that allow these credentials to use the services and their actions.
Disadvantages
This handover of credentials has several disadvantages. The main issue is that long-lasting credentials with associated permissions are given to another team. As we all know, credentials can spread quickly, which is why administrators might be hesitant to provide long-lasting credentials, even with minimal permissions.
If you plan to use many AWS services across different ODC applications, you will likely have multiple long-lasting credentials, one for each application, with limited permissions tailored to each application's needs. If you need to change credentials regularly (secret access key rotation), this can quickly become an error-prone administrative task.
It is desirable if no credentials need to be handed over at all and the AWS administrators retain absolute control over the use of services.
In this article, we take a look at how this can be achieved.
At a glance, this involves the following steps:
AWS administration configures an AWS Cognito Identity Pool that trusts federated identities from your OutSystems Developer Cloud Identity Provider.
Whenever an AWS service needs to be used, the developer exchanges the logged-in user's ODC credentials for temporary AWS credentials.
The temporary AWS credentials are then used to access an AWS service.
The image above shows the entire process. In this article, we will walk through each part involved.
Unlike the long-lasting credentials mentioned earlier, temporary credentials have a limited lifetime and expire after a certain period.
This avoids sharing permanent AWS access keys and gives admins control over permissions. It leverages Cognito's ability to issue short-lived credentials based on federated identities.
💡
The following approach is unofficial, and you should not expect support from OutSystems. However, it is valid and secure.
Identity Providers in OutSystems Developer Cloud
Let's start by looking into how Identity Management works in OutSystems Developer Cloud.
After your OutSystems Developer Cloud is set up, you can configure multiple OpenID Connect compatible Identity Providers and assign them to different stages. You can also use the built-in provider, which is also OpenID Connect compatible. Later, you can use any of these configured providers in your applications for authentication.
💡
Note that everything described in this article also works with the built-in provider. Therefore, you do not have to configure an external Identity Provider.
Under the hood OutSystems registers each of your configured Identity Providers in a KeyCloak instance in each stage you selected. This KeyCloak instance brokers authentications from the providers and issues tokens to your application including OutSystems specific claims.
💡
KeyCloak is an open-source Identity and Access Management solution largely sponsored by Redhat.
If you are curious. The built-in provider uses an AWS Cognito User Pool for authentication.
What’s important here is that only your KeyCloak instance issues tokens (Identity and Access Tokens) to your applications, not the configured and used Identity Provider in the ODC Portal, including the built-in provider.
Tokens issued by your KeyCloak instance are stored in the local storage of your client application and sent with every request to a server or service action.
Issued Access and Identity Tokens
Let's inspect how ODC credentials for applications are stored in the browser.
Open any of your ODC applications and log in. After a successful login, open the developer tools of your browser (F12 in Edge).
Switch to the Application tab, and under Storage, you should see your current stage domain name. Click on it to view the stored values on the right.
Check the value of os-runtime-currentAuthType which is set to builtin if using the default identity pool and to external if you use your own Identity Provider.
Next click on os-runtime-token which contains your personal access and identity token (id_token). Copy the value of the access token (access_token) and paste it to jwt.io for inspection.
Access Tokens - They serve as credentials that allow an OAuth client (such as a mobile app or a web application) to make requests to an API. Access tokens are primarily used for authorization. They grant the client permission to access specific resources on behalf of the user who authorized the application.
Identity Tokens - ID tokens are defined in OpenID Connect (OIDC), an extension of OAuth. OIDC is used for authentication and identity management. ID tokens provide information about what happened during the user authentication process. They serve as proof that the user has been authenticated.
Last click on os-runtime-identity-endpoints and scroll down to issuer and copy the value of the issuer field.
https://<domain-stage-name>.outsystems.app/auth/realms/<KeyCloak Realm Identifier>
This last information we are going to use to configure an AWS Cognito Identity Pool.
AWS Cognito Identity Pool
Cognito Identity Pool is a service that exchanges federated identities, like your ODC access token, for temporary AWS credentials.
Put simply, a federated identity is a user who has already authenticated with an external identity provider you trust. You configure this trust in AWS Cognito Identity Pools.
Configuring a basic Identity pool is pretty simple, but Identity Pool provides lots of advanced features like attribute based access control. Read the official documentation for details.
Create IAM Identity Provider
In your AWS account switch to the IAM console. In the menu on the left select Identity Providers and click the Add Provider button.
Paste the value of your KeyCloak realm instance here and for audience enter client_runtime.
💡
The audience value can be found by inspecting your access token's aud field. It is always client_runtime.
Repeat this step for all your stages if necessary.
Create a Cognito Identity Pool
Next switch to the AWS Cognito Console. Select Identity Pools from the menu and click on Create Identity Pool.
💡
You should create the Identity Pool in the same region your OutSystems Developer Cloud instance is running, though it is not mandatory.
Select Authenticated access (we will only allow ODC authenticated users) and in sources OpenID Connect (OIDC). Then click Next.
In the Configure Permissions screen select Create a new IAM role and type a role name.
When an access token is exchanged for AWS credentials, the permissions attached to this role are assigned to the issued credentials by default.
Click Next.
Select the OIDC Identity Provider you configured in IAM before. Leave defaults for the other options and click Next.
💡
Not covered in this article, but you should check the documentation on Role Settings and Attributes for access control. These are powerful features for fine-grained control of permissions.
In the Configure Properties screen provide a name for your Identity Pool and click Next. On the final screen review your settings and finish with Create Identity Pool.
Retrieving a User's Access Token
Before we can exchange an ODC access token for AWS credentials, we need to retrieve it. Fortunately, this is very straightforward. With every request to a server or service action, your application also sends an Authorization header with the user's access token. The header looks like this:
Bearer <Your access token value>
To get the access token we read the Authorization header using the Request_GetHeaders action from the HTTP source.
With String_Split from the Text source we can split the value by space and we return the second element (String_Split.List[1].Text.Value)
💡
If a server or service action is called from an unauthenticated user, the Authorization header is not sent. Note that Cognito is also able to issue credentials for unauthenticated (anonymous) users, though not covered in this article. Check the Cognito Identity Pools documentation on how to issue temporary AWS credentials for unauthenticated users.
Exchange for AWS Credentials
💡
You must install the AWSCognitoIdentity external logic connector from ODC Forge to perform this steps.
Having the access token, we can finally exchange it for temporary AWS credentials using a Cognito Authentication flow. The default Enhanced AuthFlow is a two-step process:
Call GetId to retrieve an IdentityId, using our access token as proof of authentication.
Use the IdentityId along with our access token to call GetCredentialsForIdentity, which returns the temporary AWS credentials.
Both actions are implemented in the AWSCognitoIdentity external logic connector.
For GetId you need to provide your Identity Pool ID which can be copied from the AWS Cognito Identity Pool console.
Add one item to the Logins list and set the Provider to your Identity Provider ID (created in IAM above). This is your KeyCloak realm name without "https://".
Set the token to the retrieved access token from the Authorization header.
GetCredentialsForIdentity takes the returned IdentityId from GetId as parameter and again the same Logins values (Identity Provider and Token).
GetCredentialsForIdentity returns temporary AWS credentials, which include an AccessKeyId, SecretAccessKey, and SessionToken. It also provides the Expiration time for these credentials.
💡
In a production environment, it makes sense to build a credential cache to reduce the number of trips to Cognito.
Using AWS Credentials
Unfortunately, there are only a few AWS connectors available on Forge that support AWS temporary credentials. At the time of writing, these are:
AWSBedrockRuntime
AWSComprehend
AWSSimpleStorage
All of these are maintained by me, and you can expect more to be added to Forge in the future. I am also trying to convince the OutSystems Platform Maintenance team to include support for temporary credentials in the officially supported integrations like Transcribe and Rekognition.
Anyhow. To use the retrieved temporary credentials with the AWSBedrockRuntime connector you choose one of the model actions and set the credential parameters accordingly.
Summary
Setting up a trust relationship between AWS Cognito Identity Pools and your OutSystems Developer Cloud environment greatly enhances security as no long-lasting credentials must be handed-over from AWS administrators to OutSystems developers. The downside is that Cognito issues temporary credentials that can only be used with a few AWS service connectors available on ODC Forge.
Thank you for reading. I hope you enjoyed it and that I've explained the important parts clearly. If not, please let me know 😊 Your feedback is greatly appreciated.
Follow me on LinkedIn to receive notifications whenever I publish something new.
One final disclaimer
As mentioned above, this is not officially supported by OutSystems. OutSystems is constantly improving and optimizing the platform, and they may not actively communicate changes to the underlying technology stack.
The only technology element used here is the trust relationship with the KeyCloak Identity Broker. If OutSystems changes the Identity Broker to something else, you would simply need to update your registered OpenId Connect Provider on the AWS side to keep it working.
Whats next
Cognito Identity Pools offer more capabilities than discussed in this article. One of the most powerful features is the ability to turn claims from your access token into AWS credential tags. This lets you set conditional IAM policies for detailed access control. For more information, check out the documentation on attribute mapping.
Also, look out for the AWS Cognito Identity JS Client ODC Forge component, which allows you to exchange an ODC access token for temporary AWS credentials directly in the client application.
