Protected Systems are applications, services, or infrastructure that you want to protect with SGNL. In this guide, we’ll describe how to achieve fine-grained access control inside of AWS with Okta and SGNL, enabling the right amount of access to infrastructure and data inside of AWS. If you’d like to learn more about whether securing AWS with Okta and SGNL is right for your enterprise, visit our Securing AWS Blog or watch the video below to learn more.
With this integration, AWS and Okta need not know about the policies, systems of record, or any of the data in SGNL - it simply needs to pass to SGNL:
Who/What is requesting the access (The Principal)
(Optional) What is attempting to be accessed (The Asset)
(Optional) What operation is being attempted on the asset (The Action)
An access token that ensures the Protected System is a legitimate caller into SGNL
Prerequisites
An AWS Organization or Account, configured with SSO to Okta
An Okta Tenant
A SGNL Client
A SGNL User Account with Admin privileges
At least 1 Okta system of record integrated to SGNL, containing principals and (optionally) assets that will be evaluated in access evaluations
(Optional) 1 or more policies that you want assigned to the integration
Creating a Protected System in SGNL
Log-In to your SGNL Client with an Admin Account
From the left navigation pane, select Protected Systems and Add, or simply click Add from the SGNL Dashboard
Select ‘AWS’ from the Infrastructure category in the list of integrations
Give your integration a descriptive display name and description
Specify the Default Policy to be applied to your App
Allow: If no policies provide a decision for an access request, SGNL will respond to the access request with an Allow decision
Deny: If no policies provide a decision for an access request, SGNL will respond to the access request with a Deny decision
Next, you’ll need to configure which identifier Okta is using to describe your user/principal
This is likely your Okta user’s email address or login name. This should be in the format of the Principal ID of the user that will request access to the Protected System.
e.g. If an Okta user will be requesting access to this Protected System, AWS, with the Principal ID as their email address, the principal identifier should be the Okta email address.
You’ll also need to define the identifiers for the types of Assets that you are looking to protect
This might be customer identifiers sourced your CRM system, or products that your customers are buying
Once configured, click Continue to save your configuration and move on to other configuration steps
Configuring Authentication
Authentication ensures that only authorized systems can make requests into SGNL, as well as verifying the identity of an integration in order to effectively evaluate Policies - to access Authentication settings, open your AWS protected system and select the Authentication tab
Click Generate Token
Give your token a descriptive name so that you know how it’s being used in the future and click to Generate Token
On the next screen, copy the token - this will be used by Okta to make access requests to SGNL using the SGNL Access Service API
Note: The value of this token is not available again after this screen, so ensure you securely store it for steps later in this guide
Integrating your Identity Provider with SGNL for dynamic AWS privilege assignment
SGNL integrates with Identity Providers at sign-in time to dynamically assign permissions, roles, tags, or other permission granting objects for AWS Access. We provide support across Okta, Entra ID, and Ping Identity to dynamically assign these permissions.
Integrating Okta with SGNL for AWS Privilege Assignment
This guide assumes you already have Okta integrated with AWS for SAML SSO. If that’s not the case, refer to AWS Documentation to get that configured.
Once configured, SGNL integrates with Okta via Inline Hooks on the Okta side, and SGNL Transforms (and optionally, Provider Hooks) on the SGNL side.
SGNL Transforms are available on the Protected System you created above, within the ‘Transforms’ Menu. To create a transform suitable for an Okta Inline Hook, you’ll want to:
Choose ‘Select a Search Transform’
Select ‘Okta SAML’
(Optional) Give the Transform a new Display Name
When configuring the ‘Request’ you’ll want to define Mapped Fields from the Okta Inline Hook Payload (Sample) that you want to map to a SGNL Search API Request
Id refers to the Principal Id, so you’ll want to select an attribute from the Inline Hook Payload the refects the Principal Id you’ve configured in the Request config for the Protected System, this is commonly Okta login ({$.data.context.user.profile.login}) or email ({$.data.context.user.profile.email}) other common options are available in the + menu
You can add the IP Address from the payload, if useful for policy decisions or simply for access log metadata, IP Address is available using {$.data.context.request.ipAddress}
Finally, choose the action you want to use, this is commonly a static string such as access or assumeRole, but it could be any of the attributes in the hook payload, using a method similar to the above
Next, you’ll want to configure how the SGNL Search API response should be formatted to return data to the Okta Inline Hook within the Response section
In almost all cases, you’ll want to use an ‘Add’ operation, to add assertions to the resulting SAML Payload from Okta – replace should only be used in circumstances where you have an existing claim in the token from Okta, that you would want SGNL to replace (n.b. trying to replace a claim that doesn’t exist will cause an Okta error)
Next, select an Asset from the SGNL search api response that you want to turn into a claim in the Okta token, this could represent an AWS Role, Tag, or something else, optionally – choose to give that Asset a custom name, for simplified explainability in the following steps
Next, you’ll want to specify a ‘Path’ where to Add/Replace that claim – if we assume you want to Add an AWS Role Claim, you could add /claims/https:~1~1aws.amazon.com~1SAML~1Attributes~1Role into this section, following the response samples in Okta’s Documentation, note that this field supports parameters from your asset response, so for something more complex like tags, you can dynamically set any part of this Path with a parameter, e.g. /claims/https:~1~1aws.amazon.com~1SAML~1Attributes~1{$.SNOWCI.Category}
Lastly, you’ll want to specify the value – this is likely to be an attribute on your asset response and if you’re wanting to dynamically assign a role in the format that AWS expects (e.g. RoleArn,SAMLProviderArn) you’ll likely need to concatenate two different parameters, e.g. {$.AWSRole.arn},arn:aws:iam::{$.AWSRole.accountId}:saml-provider/okta-saml
Continue to add more responses as you might need, or hit save to finalize the configuration
You can now (optionally) configure a Provider Hook and associate with this Transform – Provider Hooks have the benefit of requiring only a single Okta Inline Hook for multiple Protected Systems inside of SGNL
Once your SGNL Transform is configured, you can proceed to configure the Inline Hook within Okta, using the Token you copied from your Protected System above. Steps to create the Okta Inline Hook are available in Okta’s Help Documentation, ensuring that you specify HTTP Header Authentication with a Header name of ‘Authorization’ and a value that contains ‘Bearer ’ and then the token you copied from your Protected System.
Integrating Entra ID with SGNL for AWS Privilege Assignment
The first step is to configure Transforms for Entra ID
Select the Protected System
Start by going to the Settings tab, and ensure that the Asset(s) being returned in the Request Configuration section are those that you want handed back to Entra ID during SSO
Note: Transforms only manipulate the response provided by the asset search API for the chosen Protected System, they don’t allow additional querying/extraction of data from the request, from the SGNL Graph, or other sources
At this time, you might want to make a request to the asset search API to ensure that you’re returning the data you expect (or that your users actually have access to the data you expect)
Once you’re happy that policies are request configuration are correct, select the Transforms tab in the Protected System
In this example, we’re going to configure a Search Transform using Entra ID, you first need to configure the fields to map from the request, SGNL uses JSONPath to find the right values in Entra ID’s JSON request, or you can enter your own static values just by typing them in as-is – a sample request can be found in Microsoft’s Help Documentation, some sample values are provided in the console via the (+) Icon, including:
{$.data.authenticationContext.user.userPrincipalName} –> Id (SGNL Principal Id)
{$.data.authenticationContext.client.ip} – ipAddress (Principal’s IP Address)
SGNL doesn’t provide recommendations for the action context – if you’re policies don’t require an action, feel free to leave this blank, otherwise you can extract data out of Entra’s request, or provide your own static value, like sign-on
We provide significant flexibility in how to transform the response to Entra - before you get started, a couple of things to note:
You can use parameters across any number of attributes on the asset returned, though you cannot choose arbitrary attributes across multiple returned assets
SGNL’s parameter syntax takes the format of “{$.<entity or node name>.<attribute name>}”
To configure the response transforms:
Select the first asset you want to add Transforms for (i.e. When this asset is returned from the asset search API, how do you want to transform the response back to Entra)
SGNL will automatically generate a name for use in the Name and Value parameters, but change this to whatever suits your needs, it’s used only in this configuration
In the Name field, specify the Claim Name you want to return, this might be as simple as something like Role or Group, but could be far more complex, such as :
AWS Role Claim Path: /claims/https:~1~1aws.amazon.com~1SAML~1Attributes~1Role
Static AWS Principal Tag Path: /claims/https:~1~1aws.amazon.com~1SAML~1PrincipalTag:cost-centerNote: The most important thing to note here is that whatever Claim Name you return, you must have a matching Claim Name configured in the Entra ID Custom Claim Provider, you’ll get to that as part of the Provider Hook Configuration
In the Value field, specify the value of the claim that you want passed in this path, while you’re testing, this could just be a static string, but SGNL’s customers often use one or more parameters to configure the returned value, some examples:
Say you had a simple deployment in AWS with only your Okta IdP, and you wanted to dynamically assign roles, you might use an AWS IAM Role as the asset, and the arn as the attribute that you attach to your IdP string, e.g. {$.AWSIAMRole.arn},arn:aws:iam::111111111111:saml-provider/Entra-IdP
You might also have the whole ARN stored in the SGNL Graph, in that case you could simply return a single parameter without any extra detail, e.g. {$.AWSPermittedRole.arn}
A slightly more complex deployment might use the accountId from the AWSIAMRole to dynamically populate the information, e.g. {$.AWSIAMRole.arn},arn:aws:iam::{$.AWSIAMRole.account}:saml-provider/Entra-IdP
Once you’re done configuring, you can hit save, this will allow you to proceed to configuring a Provider Hook for Entra ID
Assigning Policies
Once the AWS integration is created, you can start assigning versions of Policies - to get started, select Policies from the tabs in your newly created integration
Select ‘Assign Policies’
Select:
The Policies you want to apply to the integration with the check box
The version of the Policy you want applied
Click Next once you have the Policies and Versions configured as is appropriate
Select the Enforcement mode for the Policies you chose in the previous step
Simulated: Policy Versions that are being simulated will only log their access decision in the SGNL logs and will not impact the access decision that SGNL hands back to an integration. Simulated policies are useful for performing what-if analysis of new policy versions as well as debugging policy changes.
Note: It’s considered best practice to start with policies in Simulated mode, to verify that policies have been created an applied as expected
Enforced: Policy Versions that are being enforced will impact the access decisions that SGNL hands back to an integration. Enforced Policies will determine access for an integration
Select your desired Enforcement mode and select Assign
Versions of Policies will now be Assigned to your integration
