Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

Share your experience with the FAS IT-Playbook by taking this brief survey

Federated Access for Developers

Introduction and Outline of the Problem

Access to the lower tier environments (particularly Development and Test environments) is a key need to support the development process of a software product. How developers are granted access and to what resources (and for what purposes and functions) is in part a factor of the environment itself.

A typical on-premise environment consists of one or more physical (or virtual) machines where the application server software is installed -- think web, application, and database servers. Development access to these resources are needed because the nature of on-prem development means you are configuring and manipulating these systems to install, configure, control, and monitor (usually through logging) infrastructure components. This inherently requires that developers have access to those (virtual) hardware resources in order to provide the necessary configuration and to retrieve output artifacts such as log files.

Containerized solutions move the configuration processes to a pre-deployment phase, as the container itself encapsulates the layers of configuration that interact with the hardware. This does not fundamentally change how systems are managed; it simply changes when these actions take place relative to the deployment process.

When working with a serverless solution, access to the hardware and even the server component software is not possible, as the management of these resources have been abstracted away from the developer -- these are instead managed solutions -- solutions that are managed for you. Instead, what the developer needs to access is the service provider's management console. In the case of AWS serverless solutions, this means that developers need access to the AWS Management Console.

While it is possible for an intermediary solution to abstract access away from the console, it would have to duplicate all the capabilities of the management console in order to provide adequate parity. This would be a complex and costly endeavor, with a high degree of on-going or even escalating costs, because as the provider changes existing services and capabilities or provides new services and capabilities, the intermediary solution implementation would have to expand and adapt to comply. Moreover, given the fact that the state of Serverless is such that the serverless services provided by different cloud providers vary drastically, it makes more sense economically and in regards to security to allow application developers to directly access the management console provided by the cloud provider.

It is therefore not a question of when or why to expose the service provider's management console to the developer, but more a question of how to do so in a secure and controlled manner.

Solution

The goal of this solution is to allow developers to authenticate to the team's FCS-provided AWS accounts through GSA's ENT Active Directory (AD) user registry. Doing so ensures that the mechanisms that GSA uses to onboard and offboard new team members remains consistent, and properly aligns first-line GSA access authority away from the development teams, placing the responsibility with the ENT Active Directory administrators. In short, this solution will cause a former team member's access to environments to be terminated along with their standard GSA credentials.

Implementation

The implementation requires that each AWS account that developers (or any other kind of user) need to access be configured as a separate application within Okta. Developers authenticate to GSA's ENT domain through Okta, via a SecureAuth integration.

The engineers onboarded to GSA's Okta integration accounts and assigned to configure the applications within Okta would be responsible for configuring the application for each environment:

Developers are able to use a URL (generated by Okta as part of the application configuration process) to sign them directly into the AWS Console. Whether the user first logs into Okta directly or uses the URL provided by the application configuration, the overall authentication and authorization process is thus:

Okta authenticates the user against the ENT domain via integration with SecureAuth. Once the user has been authenticated to Okta, their association with the Okta application configuration's user group is used to identify the roles they are allowed to assume within AWS.

Okta then acts as an Identity Provider (IDP) in order to authenticate the user to the AWS account. Once authentication has been completed, the user automatically assumes the associated role within the AWS account, and is presented with the AWS console.

From this point forward, the user can perform any action within the AWS Console that the assumed IAM role will allow.

SecureAuth Integration

Before configuring the application in Okta, a SecureAuth integration will be needed, in order to authenticate users against GSA's ENT domain. This is achieved via a ServiceNow Single Sign-On Integration Request. One integration is needed per Okta instance; at a minimum, this will require one for GSA's Okta Test Integration, and one for GSA's Okta Production Integration. The FALCON Team had an additional integration, used for their initial proof-of-concept; this step is recommended for getting engineering teams accustomed to the integration process between Okta and AWS, but is not required.

A URL may need to be provided to the SecureAuth team from where SecureAuth will be called; if the URL is not known at the time the ticket is being submitted, mark the field as TBD and discuss the matter with a GSA SecureAuth integration specialist who will be assigned to fulfil the ticket.

The SecureAuth team will provide an XML file in response to the ServiceNow ticket. The file describes an md:EntityDescriptor XML object. The last attribute within the md:AttributeAuthorityDescriptor object is an md:AttributeService attribute with a Binding and Location in-line attribute; the value of the Location attribute is needed while configuring an application in Okta.

The XML document should look something like this:

<md:EntityDescriptor entityID="GSASecAuthDev" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

...

    <md:AttributeService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"   

       Location="https://secureauth.gsa.gov/SecureAuthXXX/" />

  </md:AttributeAuthorityDescriptor>

</md:EntityDescriptor>

The bolded value is representative of the value that represents this specific SecureAuth integration, and will need to be called by Okta during the authentication process.

AWS IAM Configuration

The next step is to ensure that the AWS IAM resources are configured within the accounts to be accessed. There are three kinds of things that need to be configured within AWS in support of Okta authentication:

An IAM user for Okta to have access to the listing of all assumable roles

A SAML 2.0 IDP

Roles assumable by your users

Okta User

Okta needs to poll the account's IAM Roles in order to allow the team's Okta administrator to map AWS IAM Roles to Okta User Groups. This user needs to have an inline policy that allows the following:

This user also needs to have an access key, which is able to be generated on the Security credentials tab. Note, when access keys are generated, both a private and public key are provided; this is the only time when the private key will be given, and it will be needed when configuring Okta.

SAML 2.0 Identity Provider

In order to allow Okta to send principals (i.e. users) to AWS, AWS and Okta needs to be integrated through an Identity Provider. An IDP can be created through the Identity provider menu option under Access management within the AWS IAM console.

The engineer setting up the IDP within the AWS account should also be responsible for configuring the application in Okta, as they will need to obtain a metadata XML file from Okta for the Okta app in question in order to configure the AWS IDP needed to integrate Okta with AWS. Note that the IDP option selected should be for creating a SAML 2.0 Identity Provider.

Assumable Roles

The last piece of the puzzle is the creation of the AWS IAM Roles that developers will assume once they log in. Since these users are not to be defined within IAM (as they will be provided as principals via SAML), the roles need to be assumable by principals from your IDP. This can be configured within the IAM role's trust relationship.

Create one role with the appropriate permissions for each group of users that needs access. These roles will be pulled into the Okta configuration; while a single Okta Group could be assigned more than one role, for maintenance purposes, it is recommended that IAM roles be created one-to-one with the Okta groups to be associated with them.

Okta Configuration

Engineers responsible for configuring the Okta applications for each AWS environment will need to have temporary Super User access within the GSA Okta instances they are configuring; this is presently standard operating procedure for Okta integrations at GSA

Each AWS environment for which developers need access will require its own Okta application to be configured for it. The Okta application allows administrators to map Okta users (i.e. the developers) to the appropriate assumable AWS IAM roles. The Okta application starts off as an AWS Account Federation App Integration (obtainable by searching via the Browse App Catalog from within the Applications menu option).

Note that details may change with respect to the Okta user interface, however the concepts should remain the same.

When creating the integration, you will want to clear the default the AWS Login URL:

The next section allows for the specification of the ARN of the SAML 2.0 IDP created in AWS; note that this is why the same engineer configuring AWS will need to configure Okta, as these activities need to be executed simultaneously, as each needs information from the other. The XML document needed to complete the creation of the AWS IDP can be obtained from the application's Sign On tab after the creation of the app integration; you will be able to fill out the ARN field in Okta only after you have created the IDP in AWS.

The View SAML setup instructions link will take you to a page describing how to set up the SAML 2.0 IDP in AWS (same step as described earlier under AWS IAM Configuration in this document). The document will provide a link similar to this:

The actual metadata.xml document can be obtained by pasting this link into a web browser.

Within the Provisioning tab, the Enable API integration checkbox should be checked, granting access to the fields where the Access Key and Secret Key obtained during the AWS IAM configuration (Okta User, from above) can be supplied and tested.

Because Okta is a service provided by an external third party, an Okta App Sign On policy needs to be configured for each Okta application in order to require that incoming users be on the GSA Network (via VPN or VDI). The absence of this rule would allow users access to the account from non-GFE equipment (given that only VDI and GFE are allowed on the GSA Network). It is recommended that this rule be implemented for all accounts, although GSA Security Engineering has, at the time of writing, permitted access to FCS AWS accounts containing only Development environment resources.

In short, implementers may forgo the inclusion of this policy within their FCS VPCaaS Development account, but are required to enforce this policy within all other accounts.

Global Configurations

There are three items within the Okta integration account that will need to be configured at a global level.

SecureAuth IDP per Product Line

When FALCON implemented its Federated Access solution within each Okta environment (a FALCON-specific Okta integration account used for a proof-of-concept, GSA's Test Okta integration account, and GSA's Production Okta integration account), they needed to create an IDP to allow Okta to communicate with SecureAuth. This IDP was created against the metadata XML document provided by GSA's SecureAuth Team (obtainable via ServiceNow -- see above).

Any teams procuring FCS VPC-as-a-Service (VPCaaS) accounts may use the methods described within this document to provide access to their developers. However they will need to procure their own SecureAuth integration and define their own IDP within Okta. IDPs may be configured within the Identity Providers option under the Security menu.

SecureAuth IDP per Product Line

A routing rule will need to be created in order to ensure that all users signing into the Okta applications representing the team's AWS accounts will need to be configured. Routing rules can be added from the Routing Rules tab under the Identity Providers option within the Security menu.

The routing rule should be configured to route users to the appropriate IDP if they are accessing any related environmental Okta applications. This rule ensures that users of these applications will be routed through the appropriate SecureAuth integration. Remember, the SecureAuth integration is needed per Okta integration environment, so only one IDP/SecureAuth integration and routing rule is needed to handle all associated applications.

Okta Sign On Policy

Users of applications that have been authenticated by Okta against the ENT AD via SecureAuth are considered to have already passed through Multi Factor Authentication; as such, they should not be subject to further MFA prompts while signing into configured AWS accounts.

The policy pertains only to those users who are in the groups created in support of the AWS account integration to Okta. The implementation of this policy provides users who are on the GSA Network (either through VPN or VDI) a seamless Single Sign-On experience. Those users who are not on the network will still be required to authenticate to the GSA Network first. The access of AWS accounts by users not already connected to the GSA Network is not recommended in general, and at this time is only allowed for accessing accounts that contain Development environment resources only.

Other Use Cases for this Solution

While this configuration is described for the use of developers to access the AWS accounts where their environments reside, it is possible to use this solution for other scenarios. Possible scenarios for which variations of this implementation may apply could be:

In these scenarios, Okta could be used (as it is here) to map users to the appropriate roles within other tools. The first portion of the authentication process would remain the same -- integration between Okta and SecureAuth in order to act as a broker to the ENT AD; it is the integration between Okta and the tools themselves that would require further research, per tool or tool family.

If tools are to be integrated in this manner, tools associated with the same product or suite could utilize an existing SecureAuth integration. In the case of Jenkins build server that supports a given product's environments, it would be appropriate that the same integration used in the Okta applications for that product's environments would be used to support authentication into the supporting Jenkins server(s) via the creation of an additional Okta application. It would not be appropriate however, to use that same SecureAuth integration to allow users into a tool shared by the teams of multiple unrelated products (such as the second scenario -- Parliament dashboard access).

Access Control in AWS via CDK IaC

The FALCON Team uses AWS Cloud Development Kit (CDK) to define the IAM roles used within this solution to provide AWS Console permissions to users within Okta groups. By defining the roles in CDK, the team is able to rapidly update the permissions to AWS services that the developers are allowed to use. This allows the team to operate under the principle of least privilege -- providing the developers with only those permissions they need for the work at hand. Permissions can be redefined per sprint, or if different permissions are needed than initially thought, the permissions can be updated and re-deployed in mere minutes.

Using CDK to define permissions means that even the access to the environments are defined within Infrastructure as Code (IaC), allowing for clear traceability as to what permissions have been allowed and when. It also allows the administrators and DevOps engineers to use the same pipeline and build tools used to deploy the application itself to manage the level of access developers have to the environments.

Once created, the role names should not change (as they have already been pulled into Okta and associated to Okta user groups), but the permissions associated to the roles can be changed anytime, and immediately applied upon the next login of developers to the environments.

Because the environmental access controls are part of the codebase, they are able to be recreated as part of disaster recovery.