diff --git a/_source/_assets/img/avatar-jeff-taylor.jpg b/_source/_assets/img/avatar-jeff-taylor.jpg new file mode 100644 index 0000000000..a862e5339f Binary files /dev/null and b/_source/_assets/img/avatar-jeff-taylor.jpg differ diff --git a/_source/_assets/img/avatar-nick-connelly.jpg b/_source/_assets/img/avatar-nick-connelly.jpg new file mode 100644 index 0000000000..5e05b09882 Binary files /dev/null and b/_source/_assets/img/avatar-nick-connelly.jpg differ diff --git a/_source/_assets/img/avatar-raphael.jpg b/_source/_assets/img/avatar-raphael.jpg index 32a92f9042..51fbaea4d1 100644 Binary files a/_source/_assets/img/avatar-raphael.jpg and b/_source/_assets/img/avatar-raphael.jpg differ diff --git a/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api-request-headers.jpg b/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api-request-headers.jpg new file mode 100644 index 0000000000..846d9e7c03 Binary files /dev/null and b/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api-request-headers.jpg differ diff --git a/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api.jpg b/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api.jpg new file mode 100644 index 0000000000..0c0a51b89e Binary files /dev/null and b/_source/_assets/img/blog/angular-dpop-jwt/bearer-network-users-api.jpg differ diff --git a/_source/_assets/img/blog/angular-dpop-jwt/dpop-token-fail.jpg b/_source/_assets/img/blog/angular-dpop-jwt/dpop-token-fail.jpg new file mode 100644 index 0000000000..21c97e72fd Binary files /dev/null and b/_source/_assets/img/blog/angular-dpop-jwt/dpop-token-fail.jpg differ diff --git a/_source/_assets/img/blog/angular-dpop-jwt/local-storage-tokens.jpg b/_source/_assets/img/blog/angular-dpop-jwt/local-storage-tokens.jpg new file mode 100644 index 0000000000..0f0bc47d46 Binary files /dev/null and b/_source/_assets/img/blog/angular-dpop-jwt/local-storage-tokens.jpg differ diff --git a/_source/_assets/img/blog/angular-dpop-jwt/social.jpg b/_source/_assets/img/blog/angular-dpop-jwt/social.jpg new file mode 100644 index 0000000000..200c9bcdd0 Binary files /dev/null and b/_source/_assets/img/blog/angular-dpop-jwt/social.jpg differ diff --git a/_source/_assets/img/blog/dpop-oauth-node/dpopflow.jpg b/_source/_assets/img/blog/dpop-oauth-node/dpopflow.jpg new file mode 100644 index 0000000000..2448d1f3eb Binary files /dev/null and b/_source/_assets/img/blog/dpop-oauth-node/dpopflow.jpg differ diff --git a/_source/_assets/img/blog/dpop-oauth-node/social.jpg b/_source/_assets/img/blog/dpop-oauth-node/social.jpg new file mode 100644 index 0000000000..db0a328e4f Binary files /dev/null and b/_source/_assets/img/blog/dpop-oauth-node/social.jpg differ diff --git a/_source/_assets/img/blog/dpop-oauth/social.jpg b/_source/_assets/img/blog/dpop-oauth/social.jpg new file mode 100644 index 0000000000..92963d8d24 Binary files /dev/null and b/_source/_assets/img/blog/dpop-oauth/social.jpg differ diff --git a/_source/_assets/img/blog/dpop-oauth/token-request-with-nonce.svg b/_source/_assets/img/blog/dpop-oauth/token-request-with-nonce.svg new file mode 100644 index 0000000000..a50372839b --- /dev/null +++ b/_source/_assets/img/blog/dpop-oauth/token-request-with-nonce.svg @@ -0,0 +1,3 @@ + + +Authorization ServerClientAuthorization ServerClientRedirect to sign-in page for user challengeRedirect to client with authorization codeGenerate public/private key and DPoP proofRequest token sending DPoP proof and codeError! Here's a nonce for youGenerate DPoP proof with nonceRequest token sending DPoP proof with nonce and codeToken bound to proof \ No newline at end of file diff --git a/_source/_assets/img/blog/dpop-oauth/token-request.svg b/_source/_assets/img/blog/dpop-oauth/token-request.svg new file mode 100644 index 0000000000..32589ecf46 --- /dev/null +++ b/_source/_assets/img/blog/dpop-oauth/token-request.svg @@ -0,0 +1,3 @@ + + +Authorization ServerClientAuthorization ServerClientRedirect to sign-in page for user challengeRedirect to client with authorization codeGenerate public/private key and DPoP proofRequest token sending DPoP proof and codeToken bound to proof \ No newline at end of file diff --git a/_source/_assets/img/blog/oktane-saas-developers/social.jpg b/_source/_assets/img/blog/oktane-saas-developers/social.jpg new file mode 100644 index 0000000000..3ecf368554 Binary files /dev/null and b/_source/_assets/img/blog/oktane-saas-developers/social.jpg differ diff --git a/_source/_assets/img/blog/terraform-ci-cd/architecture-overview.jpg b/_source/_assets/img/blog/terraform-ci-cd/architecture-overview.jpg new file mode 100644 index 0000000000..b9d095760d Binary files /dev/null and b/_source/_assets/img/blog/terraform-ci-cd/architecture-overview.jpg differ diff --git a/_source/_assets/img/blog/terraform-ci-cd/module-files.jpg b/_source/_assets/img/blog/terraform-ci-cd/module-files.jpg new file mode 100644 index 0000000000..0b71192556 Binary files /dev/null and b/_source/_assets/img/blog/terraform-ci-cd/module-files.jpg differ diff --git a/_source/_assets/img/blog/terraform-ci-cd/social.jpg b/_source/_assets/img/blog/terraform-ci-cd/social.jpg new file mode 100644 index 0000000000..1ceabb00aa Binary files /dev/null and b/_source/_assets/img/blog/terraform-ci-cd/social.jpg differ diff --git a/_source/_assets/img/blog/terraform-ci-cd/workflow.jpg b/_source/_assets/img/blog/terraform-ci-cd/workflow.jpg new file mode 100644 index 0000000000..12443368d9 Binary files /dev/null and b/_source/_assets/img/blog/terraform-ci-cd/workflow.jpg differ diff --git a/_source/_data/authors.yml b/_source/_data/authors.yml index 19e01d67de..91bfc74800 100644 --- a/_source/_data/authors.yml +++ b/_source/_data/authors.yml @@ -40,7 +40,7 @@ maurice-sharp: email: maurice.sharp@okta.com linkedin: https://www.linkedin.com/in/msharp/ bio: Maurice is a developer, author, and documentation writer. He transitioned to developer documentation after writing a book on coding for iPhone. He went from managing a mobile development team to documenting Apple developer APIs. Then he moved to Okta where he focuses on developer content strategy and writes the occasional article. - Outside of work, he occasionally gives a workshop on designing and delivering engaging stories using a methodology based on cognitive biology and brain function. He's given these to presenters, entrepreneurs pitching VCs, and others. He uses the same methodology for writing documentation. + Outside of work, he occasionally gives a workshop on designing and delivering engaging stories using a methodology based on cognitive biology and brain function. He's given these to presenters, entrepreneurs pitching VCs, and others. He uses the same methodology for writing documentation. victor-ronin: @@ -952,3 +952,18 @@ louie-campagna: avatar: avatar-louie-campagna.jpeg linkedin: https://www.linkedin.com/in/louie-campagna/ bio: Louie Campagna is an Okta Developer Support Engineer. He enjoys coding creative solutions to problems and writing scripts to automate processes. Louie's previous experience spans across customer service, desktop engineering, identity and access management and governance, and programming. + +nick-connelly: + full_name: Nick Connelly + display_name: Nick Connelly + avatar: avatar-nick-connelly.jpg + linkedin: https://www.linkedin.com/in/nicholasconnelly/ + bio: Nick Connelly is a seasoned Professional Consultant within the Okta Professional Services team, bringing over a decade of experience in cybersecurity and identity and access management. Passionate about learning new technologies and improving processes, Nick is dedicated to delivering exceptional value for customers by leveraging the latest advancements and best practices in the industry. + +jeff-taylor: + full_name: Jeff Taylor + display_name: Jeff Taylor + avatar: avatar-jeff-taylor.jpg + linkedin: https://www.linkedin.com/in/jeffctaylor/ + github: https://github.com/jefftaylor-okta + bio: Jeff is a Group Product Manager working on our Developer Products for Developers and Operators working with Workforce Identity Cloud including helping Integrators submitting to the Okta Integration Network easily and effectively. Jeff is a champion for Builders on the Okta ecosystem. diff --git a/_source/_includes/header.html b/_source/_includes/header.html index 67c1389f45..d9f16ce93f 100644 --- a/_source/_includes/header.html +++ b/_source/_includes/header.html @@ -75,7 +75,7 @@
  • - Blog + Blog
  • diff --git a/_source/_includes/promo_banner.html b/_source/_includes/promo_banner.html index 1e6c4907da..9c38f83d5e 100644 --- a/_source/_includes/promo_banner.html +++ b/_source/_includes/promo_banner.html @@ -1,4 +1,4 @@ -{% assign show_promo_banner = true %} +{% assign show_promo_banner = false %} {% assign documentation_subdirs = "docs,standards,use_cases,reference,authentication-guide" | split:"," %} {% for dir in documentation_subdirs %} @@ -8,11 +8,11 @@ {% endfor %} {% if show_promo_banner %} - +
    - Check out the free virtual workshops on how to take your SaaS app to the next level in the enterprise-ready identity journey! + See you at Oktane in Las Vegas on October 15-17, 2024. Read more about the activities planned with you mind here. >+A: Redirect to sign-in page for user challenge + A-->>-C: Redirect to client with authorization code + C->C: Generate public/private key and DPoP proof + C->>+A: Request token sending DPoP proof and code + A->>-C: Token bound to proof +{% endcomment %} + +The proof contains metadata proving the sender and ways to limit unauthorized use by limiting the HTTP request, the validity window, and reuse. If you inspect a decoded DPoP proof JWT, you'll see the header contains information proving the sender: + * The `typ` claim set to `dpop+jwt` + * The public/private key encryption algorithm + * The public key in [JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517) format + +Inspecting the decoded proof's payload shows claims that limit unauthorized use, such as: + * HTTP request info including the URI and HTTP method (such as `https://{yourOktaDomain}/oauth2/v1/token` and `POST`) + * Issue time to limit the validity window for the proof + * An identifier that's unique within the validity window to mitigate replay attacks + +Let's inspect the `/token` request a little further. When making the request, the client adds the proof in the header. The rest of the request, including the grant type and the code itself, remains the same for the Authorization Code flow. + +```http +POST https://{yourOktaDomain}/oauth2/v1/token HTTP/1.1 +DPoP: eyJ0eXAiOiJkcG9w.....H8-u9gaK2-oIj8ipg +Accept: application/json +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code +code=XGa_U6toXP0Rvc.....SnHO6bxX0ikK1ss-nA +``` + +The authorization server decodes the proof and incorporates properties from the JWT into the access token. The authorization server responds to the `/token` request with the token and explicitly sets the response header to state the token type as `DPoP`. + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ +"access_token":"eyJhbG1NiIsPOk.....6yJV_adQssw5c", +"token_type":"DPoP", +"expires_in":3600, +"refresh_token":"5PybPBQRBKy2cwbPtko0aqiX" +} +``` + +You now have a DPoP type access token with a possession proof. What changes when requesting resources? + +## Use DPoP-bound access tokens in HTTP requests + +DPoP tokens are no longer bearer tokens; the token is now "sender-constrained." The sender, the client application calling the resource server, must have both the access token and a valid proof, which requires the private key held by the client. This means malicious sorts need both pieces of information to impersonate calls into the server. The spec builds in constraints even if a malicious sort steals the token and the proof. The proof limits the call to a unique request for the URI and method within a validity window. Plus, your application system still has the defensive web security measures applicable to all web apps, preventing the leaking of sensitive data such as tokens and keysets. + +The client generates a new proof for each HTTP request and adds a new property, a hash of the access token. The hash further binds the proof to the access token itself, adding another layer of sender constraint. The proof's payload now includes: + * HTTP request info including the URI and HTTP method (such as `https://{yourResourceServer}/resource` and `GET`) + * Issue time to limit the validity window for the proof + * An identifier that's unique within the validity window to mitigate replay attacks + * Hash of the access token + +Clients request resources by sending the access token in the `Authorization` header, along with proof demonstrating they're the legitimate holders of the access token to resource servers using a new scheme, `DPoP`. HTTP requests to the resource server change to + +```http +GET https://{yourResourceServer}/resource HTTP/1.1 +Accept: application/json +Authorization: DPop eyJhbG1NiIsPOk.....6yJV_adQssw5c +DPoP: eyJhbGciOiJIUzI1.....-DZQ1NI8V-OG4g +``` + +The resource server verifies the validity of the access token and the proof before responding with the requested resource. + +## Extend the DPoP flow with an enhanced security handshake + +DPoP optionally defines an enhanced handshake mechanism for calls requiring extra security measures. The client _could_ sneakily create proofs for future use by setting the issued time in advance, but the authorization and resource servers can wield their weapon, the nonce. The nonce is an opaque value the server creates to limit the request's lifetime. If the client makes a high-security request, the authorization or resource server may issue a nonce that the client incorporates within the proof. Doing so binds the specific request and time of the request to the server. + +An example of a highly secure request is when making the initial token request. Okta follows this pattern. Different industries may apply guidance and rules for the types of resource server requests requiring a nonce. Since the enhancement requires an extra HTTP request, use it minimally. + +When the authorization server's `/token` request requires a nonce, the server rejects the request and returns an error. The response includes a new header type, `DPoP-Nonce`, with the nonce value, and a new standard error message, `use_dpop_nonce`. The flow for requesting tokens now looks like this: + +{% img blog/dpop-oauth/token-request-with-nonce.svg alt:"Sequence diagram where client redirects to authorization server for user challenge. The authorization server redirects back to the client with the authorization code. The client generates a public/private key and creates the proof. The client sends the proof in the token request. The authorization server rejects the request and returns a nonce. The client regenerates the proof with nonce incorporated and re-requests the tokens. The authorization server returns an access token bound to the proof." width:"800" %} + +{% comment %} +Tweak the diagram on https://mermaid.live/ with the following content +sequenceDiagram + participant C as Client + participant A as Authorization Server + C-->>+A: Redirect to sign-in page for user challenge + A-->>-C: Redirect to client with authorization code + C->C: Generate public/private key and DPoP proof + C->>+A: Request token sending DPoP proof and code + A->>-C: Error! Here's a nonce for you + C->C: Generate DPoP proof with nonce + C->>+A: Request token sending DPoP proof with nonce and code + A->>-C: Token bound to proof +{% endcomment %} + +Let's look at the HTTP response from the authorization and resource servers requiring a nonce. The authorization server responds to the initial token request with a `400 Bad Request` and the needed nonce and error information. + +```http +HTTP/1.1 400 Bad Request +DPoP-Nonce: server-generated-nonce-value + +{ + "error": "use_dpop_nonce", + "error_description": "Authorization server requires nonce in DPoP proof" +} +``` + +When the resource server requires a nonce, the response changes. The resource server returns a `401 Unauthorized` with the `DPoP-Nonce` header and a `WWW-Authenticate` header containing the `use_dpop_nonce` error message. + +```http +HTTP/1.1 401 Unauthorized +DPoP-Nonce: server-generated-nonce-value +WWW-Authenticate: error="use_dpop_nonce", error_description="Resource server requires nonce in DPoP proof" +``` + +We want that resource, so it's time for a new proof! The client reacts to the error and generates a new proof with the following info in the payload: + * HTTP request info including the URI and HTTP method (such as `https://{yourResourceServer}/resource` and `GET`) + * Issue time to limit the validity window for the proof + * An identifier that's unique within the validity window to mitigate replay attacks + * The server-provided nonce value + * Hash of the access token + +With this new proof, the client can remake the request. + +## Validate DPoP requests in the resource server + +Okta's API resources support DPoP-enabled requests. If you want to add DPoP support to your own resource server, you must validate the request. You'll decode the proof to verify the properties in the header and payload sections of the JWT. You'll also need to verify properties within the access token. OAuth 2.0 access tokens can be opaque, so use your authorization server's `/introspect` endpoint to get token properties. Okta's API security guide, [Configure OAuth 2.0 Demonstrating Proof-of-Possession](https://developer.okta.com/docs/guides/dpop/nonoktaresourceserver/main/#make-a-request-to-a-non-okta-resource) has a step-by-step guide on validating DPoP tokens, but you should use a well-maintained and vetted OAuth 2.0 library to do this for you instead. Finally, enforce any application-defined access control measures before returning a response. + +## Learn more about OAuth 2.0, Demonstrating Proof-of-Possession, and secure token practices + +I hope this intro to sender-constrained tokens is helpful and inspires you to use DPoP to elevate token security! Watch for more content about DPoP, including hands-on experimentation and code projects. If you found this post interesting, you may also like these resources: + +* [Secure OAuth 2.0 Access Tokens with Proofs of Possession](/blog/2024/09/10/angular-dpop-jwt) +* [Why You Should Migrate to OAuth 2.0 From Static API Tokens](/blog/2023/09/25/oauth-api-tokens) +* [How to Secure the SaaS Apps of the Future](https://sec.okta.com/appsofthefuture) +* [Step-up Authentication in Modern Application](/blog/2023/03/08/step-up-auth) +* [OAuth 2.0 Security Enhancements](https://auth0.com/blog/oauth2-security-enhancements/) +* [Add Step-up Authentication Using Angular and NestJS](/blog/2024/03/12/stepup-authentication) + +Remember to follow us on [Twitter](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/c/OktaDev/) for more exciting content. We also want to hear from you about topics you want to see and questions you may have. Leave us a comment below! diff --git a/_source/_posts/2024-09-10-angular-dpop-jwt.md b/_source/_posts/2024-09-10-angular-dpop-jwt.md new file mode 100644 index 0000000000..9ebf21ea4f --- /dev/null +++ b/_source/_posts/2024-09-10-angular-dpop-jwt.md @@ -0,0 +1,397 @@ +--- +layout: blog_post +title: "Secure OAuth 2.0 Access Tokens with Proofs of Possession" +author: alisa-duncan +by: advocate +communities: [security, javascript] +description: "Elevate access token security by demonstrating proof of possession (DPoP). Migrate a SPA to use DPoP in this hands-on project." +tags: [angular, react, vue, spa, authorization] +image: blog/angular-dpop-jwt/social.jpg +type: conversion +github: https://github.com/oktadev/okta-angular-dpop-example +--- + +In OAuth, a valid access token grants the caller access to resources and the ability to perform actions on the resources. This means the access token is powerful and dangerous if it falls into malicious hands. The traditional bearer token scheme means the token grants anyone who possesses it access. A new OAuth 2.0 extension specification, [Demonstrating Proof of Possession (DPoP)](https://www.rfc-editor.org/rfc/rfc9449), defines a standard way that binds the access token to the OAuth client sending the request elevating access token security. + +The high-level overview of DPoP uses public/private keys to create a signed DPoP proof that the authorization and resource server use to confirm the authenticity of the request and requesting client. This way, the token is sender-constrained, and a token thief is less likely to use a compromised access token. Learn more about the problems DPoP solves and how it works by reading: + +{% excerpt /blog/2024/09/05/dpop-oauth %} + +The primary use case for DPoP is for public clients, but the spec elevates token security for all OAuth client types. Public clients are applications where authentication code runs within the end user's browser, such as Single-Page Applications (SPA) and mobile apps. Due to their architecture, public clients inherently have higher risk and less security in authentication and authorization. Public clients can't leverage a client secret used by application types that can communicate to the authorization server through a "back-channel," a network connection opaque to users, network sniffing attackers, and nosy developers. Without proper protection, a SPA may store tokens accessible to the end-user and injection-related attacks. DPoP adds an extra protection layer that makes tokens less usable if stolen. + +**Table of Contents**{: .hide } +* Table of Contents +{:toc} + +In this post, you'll experiment with DPoP and step through migrating a public client application using OAuth bearer tokens compared to DPoP tokens. We'll build upon the existing OAuth 2.0 Authorization Code flow. Need a refresher? Check out this post: + +{% excerpt /blog/2023/04/04/spa-auth-tokens %} + +> **Note** +> +> This code project is best for developers with web development experience, knowledge of debugging network requests and responses, and familiarity with OAuth and OpenID Connect (OIDC). +> +> The post uses Angular, but you can follow the concepts and network calls using a sample project in your favorite SPA framework. Check out samples using [React](https://github.com/okta-samples/okta-react-sample) or [Vue](https://github.com/okta-samples/okta-vue-sample). You'll need to make a couple of minimal changes to the code. I will call out the changes, but I will not post the specific code or instructions. +> +> Are you following the step-by-step code instructions in Angular? This post assumes you already have Angular knowledge. If you are an Angular newbie, start by building [your first Angular app](https://angular.io/tutorial/first-app) using the tutorial created by the Angular team. + +A hands-on project requires tools for local web development. + +**Prerequisites** + +You'll need the following tools: + * [Node.js](https://nodejs.org/en) v18 or greater + * A web browser with good debugging capabilities, such as Chrome + * Your favorite IDE. Still looking? I like VS Code and WebStorm because they have integrated terminal windows. + * Terminal window (if you aren't using an IDE with a built-in terminal) + * [Git](https://git-scm.com/) and an optional [GitHub account](https://github.com/) if you want to track your changes using a source control manager + * An HTTP client that shows the HTTP requests and responses, such as the [Http Client VS Code extension](https://marketplace.visualstudio.com/items?itemName=Aaron00101010.http-client) or [curl](https://curl.se/) + +## Get the starting Angular, React, or Vue project + +You'll use a starter project. These instructions are for the Angular sample project. If you are following along in [React](https://github.com/okta-samples/okta-react-sample) or [Vue](https://github.com/okta-samples/okta-vue-sample), replace the GitHub repo location with the URL for the sample you're using. + +Open a terminal window and run the following commands to get a local copy of the project in an `okta-client-dpop-project` directory and install dependencies. Feel free to fork the repo so you can track your changes. + +```shell +git clone https://github.com/oktadev/okta-angular-dpop-example.git okta-client-dpop-project +cd okta-client-dpop-project +npm ci +``` + +Open the project in your favorite IDE. The project includes Okta's client authentication SDKs, a sign-in button, a profile route that displays user information by calling the OIDC `/userinfo` endpoint, and a route that makes a call to [Okta's Users API](https://developer.okta.com/docs/reference/api/users/). Both HTTP requests require an access token, so we'll follow the requests and responses for these two calls. + +> **React and Vue project instructions** +> +> React and Vue projects need a couple of changes. Change the profile component to call `oktaAuth.token.getUserInfo()` and display the JSON output. Add a call to Okta's User API `https://{yourOktaDomain}/api/v1/users`. You'll replace the domain name later. You may want to create a new Users component (and route) to match the Angular sample. +> +> Use the SDK reference docs for [React](https://github.com/okta/okta-react?tab=readme-ov-file#okta-react-sdk) and [Vue](https://github.com/okta/okta-vue?tab=readme-ov-file#okta-vue-sdk). + +You need to set up an authentication configuration to serve the project. Let's do so now. + +## Add OAuth 2.0 and OpenID Connect (OIDC) to your application + +You'll use Okta to handle authentication and authorization in this project securely. Okta APIs have built-in DPoP support — how secure and handy! We'll experiment with DPoP in the client application by calling Okta's APIs. + +> **React and Vue project instructions** +> +> Replace the two redirect URIs to match the port and callback route for the application. You'll find the URI for both in your project's README file. Follow the instructions in the README to add the issuer and client ID to the app. Use the format `https://{yourOktaDomain}` for the issuer. Notice this is different from the starter code. + +{% include setup/cli.md type="spa" framework="Angular" loginRedirectUri="http://localhost:4200/login/callback" logoutRedirectUri="http://localhost:4200" %} + +Note the `Issuer` and the `Client ID`. You'll need those values for your authentication configuration, which is coming soon. + +There's one manual change to make in the Okta Admin Console. Add the **Refresh Token** grant type to your Okta Application. Open a browser tab to sign in to your [Okta developer account](https://developer.okta.com/login/). Navigate to **Applications** > **Applications** and find the Okta Application you created. Select the name to edit the application. Find the **General Settings** section and press the **Edit** button to add a Grant type. Activate the **Refresh Token** checkbox and press **Save**. + +Leave the Okta Admin console open. You'll continue making changes in there. + +I already added [Okta Angular](https://www.npmjs.com/package/@okta/okta-angular) and [Okta Auth JS](https://www.npmjs.com/package/@okta/okta-auth-js) libraries to connect our Angular application with Okta authentication. + +In your IDE, open `src/app/app.config.ts` and find the `OktaAuthModule.forRoot()` configuration. Replace `{yourOktaDomain}` and `{yourClientID}` with the values from the Okta CLI. + +### Configure OAuth scopes for Okta API calls + +We're calling an Okta API, so we must add the required OAuth scopes. + +In the Okta Admin Console, navigate to the **Okta API Scopes** tab in your Okta application. Find the `okta.apps.read` and `okta.users.read.self` and press the **✔️ Grant** button for each. + +Open the `src/app/users/users.component.ts` and find the call to [list users](https://developer.okta.com/docs/reference/api/users/#list-users): `https://{yourOktaDomain}/api/v1/users`. We're taking shortcuts here, such as calling the API directly in the component for this demonstration project. In production-quality Angular apps, ensure you architect your application following best practices so you can add automated tests and troubleshoot issues quickly. + +Replace `{yourOktaDomain}` with your Okta domain. + +> **React and Vue project instructions** +> +> Add the two scopes to the OIDC configuration for the application. Search for "scopes" and change the array to +> +> ```js +> scopes: ['openid', 'profile', 'email', 'offline_access', 'okta.users.read.self', 'okta.apps.read'], +> ``` +> +> Replace the `{yourOktaDomain}` in the Okta Users API call you added in the prior section. + +Start the app by running: + +```shell +npm start +``` + +Open a browser tab to view the app. Open the debugging view that shows the console and network requests. Since I am using Chrome, I'll open DevTools. Enable **Preserve log** in the **Console** and **Network** tabs. For the **Console** tab, you'll find the preserve log option after opening the gear menu. + +Let's ensure you can sign in, call the `/userinfo` endpoint to see your user information, and call Okta Users API. You'll use the Authorization Code flow and redirect to Okta for the authentication challenge. Once you emerge victorious by assuring the identity provider you are who you claim to be, the authorization server redirects you back to the application. The redirect URI includes the authorization code. Okta's SDK (the OIDC client library) calls the `/token` endpoint to exchange the authorization code for tokens. + +After you sign in, the Angular app will display routes for "Profile" and "Users." Navigating these routes calls the `/userinfo` and Users API. If you can access the routes and don't see any HTTP request errors, you're good to go! + +## Inspect the OAuth 2.0 bearer tokens and request resources manually + +After signing in, you have the OAuth 2.0 access token and the OIDC ID token. Okta stores the tokens in browser storage. In DevTools, open the **Application** tab to view browser storage data. Okta Auth JS defaults to local storage for tokens and is configurable based on your application needs. Expand **Local storage**, select the application, and expand the `okta-token-storage` key to see the tokens and token metadata. The `tokenType` property is `Bearer`. + +{% img blog/angular-dpop-jwt/local-storage-tokens.jpg alt:"Browser local storage showing Okta's token storage. The access token has the token in JWT format as well as scopes, claims, and token type as top-level properties." width:"800" %}{: .center-image } + +Let's see the API calls in action in the application. Navigate to both routes. In the **Network** tab, you see the initial `/token`, `/userinfo`, and Users API requests. + +Let's inspect the Users API request. + +{% img blog/angular-dpop-jwt/bearer-network-users-api.jpg alt:"Network requests showing calls to token, userinfo, and users endpoints. the users api call shows a 200 OK status code." width:"800" %}{: .center-image } + +The request includes the `Authorization` header containing the token scheme and access token. You see the format `Bearer `. + +{% img blog/angular-dpop-jwt/bearer-network-users-api-request-headers.jpg alt:"Users API request headers showing the Authorization header." width:"800" %}{: .center-image } + +The entity holding the token can legitimately request resources. Let's try using the token in another client and impersonating the actions an attacker can take if they manage to capture it. + +> **Note** +> +> Access tokens expire quickly. If too much time passes in these next steps, you may get a `401 Unauthorized`. If you do, repeat the steps with a more recent access token by navigating between the profile and user routes to trigger a call to the API. It prompts the OIDC client (the Okta Auth JS SDK) to update expired tokens. + +Copy the token from the browser, and double-check you captured the entire token. Open your HTTP client and run the following HTTP request replacing `{yourOktaDomain}` and `{yourAccessToken}`: + +```http +GET https://{yourOktaDomain}/api/v1/users HTTP/1.1 +Authorization: Bearer {yourAccessToken} +``` + +If you use curl, add the verbose flag to see the request and response headers: + +```curl +curl -v --header "Authorization: Bearer {yourAccessToken}" https://{yourOktaDomain}/api/v1/users +``` + +The call succeeds even though the HTTP client isn't the same client the authorization server issued the token to (the sample app). + +Let's call another endpoint with the same access token, the Okta Applications endpoint. Run the following HTTP request replacing `{yourOktaDomain}` and `{yourAccessToken}`: + +```http +GET https://alisa.oktapreview.com/api/v1/apps HTTP/1.1 +Authorization: Bearer {yourAccessToken} +``` + +The call succeeds even though you call from a different client, like you saw in the prior step, calling the Users API. The call succeeds for a privileged user as long as the Okta Application has the `okta.apps.read` and the OIDC config has the scope. You may say that's a lot of constraints, and you're right. Okta adds a lot of guards when making API requests about the resources in the top-level Okta org, such as the list of Okta applications. This example demonstrates how powerful and vulnerable tokens issued for privileged users like admins are. Anyone with the token can make the same request, even if they are an attacker. + +Back in the app, sign out to clear the authenticated session and tokens. We're making changes that require you to sign in from scratch. + +## Use secure coding techniques to protect your web apps + +All web applications must use secure coding techniques to protect from attacks, breaches, and malicious use. Public clients store their tokens within the user's hardware and require thoughtful security practices. Read more about SPA web security and security practices within Angular in this four-part series: + +{% excerpt /blog/2022/07/06/spa-web-security %} + +It doesn't matter if your application uses bearer tokens or DPoP; apps must employ secure coding practices. DPoP doesn't prevent attackers from stealing your token but constrains its use. DPoP uses asymmetric encryption to prove token ownership, so you must avoid exfiltration or unauthorized use of the keyset. An attacker can create valid proofs if they get a hold of the private key. + +Let's migrate the application to DPoP and try making these HTTP requests again. + +## Migrate your SPA to use DPoP + +Open the Okta Admin Console in the browser and navigate to **Applications** > **Applications**. Find the Okta application for this project. In the **General** tab, find the **General Settings** section and press **Edit**. Check the **Proof of possession** checkbox requiring the DPoP header in token requests. Press **Save**. Sign out of the Okta Admin Console. + +If you try signing in again without making any code changes, you'll see an error in the Network tab for the `/token` request: + +```http +HTTP/1.1 400 Bad Request + +{ + "error": "invalid_dpop_proof", + "error_description": "The DPoP proof JWT header is missing." +} +``` + +All HTTP requests to DPoP-protected resources (including the `/token` request) require proof. We must enable DPoP in the OIDC configuration. + +The Okta Auth JS SDK has a [configuration property for DPoP](https://github.com/okta/okta-auth-js?tab=readme-ov-file#enabling-dpop) as part of the OIDC config. In your IDE, open `src/app/app.config.ts` and find the `OktaAuthModule.forRoot()` configuration. Add the `dpop: true` property. Your OIDC config will look something like this: + +```js +{ + issuer: ..., + clientId: ..., + redirectUri: ..., + scopes: ['openid', 'profile', 'offline_access', 'okta.users.read.self', 'okta.apps.read'], + dpop: true +} +``` + +Once the application rebuilds and reloads in the browser, make sure you have debugging tools open and then sign in. + +## Trace the token request requiring a DPoP nonce + +When you sign in, you'll see the initial call to the `/token` endpoint fails. + +{% img blog/angular-dpop-jwt/dpop-token-fail.jpg alt:"Network requests showing the first call fails with HTTP status 400 and the second call succeeds." width:"800" %}{: .center-image } + +Take a look at the call's request headers. You'll see a header called `DPoP`, which contains the DPoP proof in JWT format, which means we can decode it and inspect its contents. You can use a trustworthy online tool such as [JWT.io debugger](jwt.io) or Base64 decode the header and payload sections of the JWT locally. In the JWT format, the content from the beginning up to the first . character is the header, and the content between the two . characters is the payload. + +The header contains the token type, `dpop+jwt`, the encryption algorithm, and the cryptographic key information tied to this proof. The payload includes minimal HTTP information and other properties to prevent token attack vectors. + +```json +{ + "alg": "RS256", + "typ": "dpop+jwt", + "jwk": { /* Key information in JSON Web Key format */ } +} + +{ + "htm":"POST", + "htu":"https://{yourOktaDomain}/oauth2/v1/token", + "iat":1724685617, + "jti": "e84a...283bbf", +} +``` + +Why did the initial call to `/token` fail? It's because Okta requires an extra handshake that elevates security. The `/token` call requires a DPoP nonce that Okta provides included in the DPoP proof. In response to the first `/token` call, Okta returns the standard DPoP nonce error and the `DPoP-Nonce` response header containing the nonce the client incorporates into the proof. + +```http +HTTP/1.1 400 Bad Request +DPoP-Nonce: "SVD....ubNc" + +{ + "error": "use_dpop_nonce", + "error_description": "Authorization server requires nonce in DPoP proof." +} +``` + +Okta's Auth JS SDK has built-in support for `DPoP-Nonce` errors. Look at the DPoP proof token's payload of the successful `/token` request. The payload includes the nonce returned in the first call. + +```json +{ + "htm":"POST", + "htu":"https://{yourOktaDomain}/oauth2/v1/token", + "iat":1724685617, + "jti": "e852...28396", + "nonce":"SVD....ubNc" +} +``` + +The token request succeeds, and we now have a DPoP access token. + +## Request resources using DPoP headers + +In the app, navigating to view your profile succeeds because the SDK supports DPoP resource requests. You'll see an error when navigating the "Users" route that calls Okta's User API. + +The HTTP response includes information about why the call errored. + +```http +HTTP/1.1 400 Bad Request +WWW-Authenticate: Bearer authorization_uri="http://{yourOktaDomain}/oauth2/v1/authorize", realm="http://{yourOktaDomain}", scope="okta.users.read.self", error="invalid_request", error_description="The resource request requires a DPoP proof.", resource="/api/v1/users" +``` + +The current code to make the Users API call adds the access token using the `Bearer` scheme in the `Authorization` header, but that's incorrect for DPoP. We must incorporate the DPoP proof and change the scheme in the HTTP request. + +Open the auth interceptor in the IDE. You can find the code in the `src/app/auth.interceptor.ts` file. + +> **React and Vue project instructions** +> +> Find the code you added to request Users and incorporate the Angular instructions in the project to add the DPoP proof header and the `DPoP` scheme. + +The interceptor has a check to ensure it adds the access token to allowed origins only. Change the interceptor code as follows: + +```ts +export const authInterceptor: HttpInterceptorFn = (req, next, oktaAuth = inject(OKTA_AUTH)) => { + let request = req; + const allowedOrigins = ['/api']; + if (!allowedOrigins.find(origin => req.url.includes(origin))) { + return next(request); + } +}; +``` + +We need the proof and the authorization header. We'll generate both using Okta Auth JS. The SDK method requires the HTTP method and URI we intend to call. The URI shouldn't include query parameters or fragments. The SDK method returns an object with properties matching headers and their values, so we can use the spread operator to populate the DPoP-required headers. + +Change the interceptor to match the code below. + +```ts +import { DPoPHeaders } from '@okta/okta-auth-js'; +import { defer, map, switchMap } from 'rxjs'; + +export const authInterceptor: HttpInterceptorFn = (req, next, oktaAuth = inject(OKTA_AUTH)) => { + // allowed origin check + + const url = new URL(req.url); + + return defer(() => oktaAuth.getDPoPAuthorizationHeaders({url: `${url.origin}${url.pathname}`, method: req.method})).pipe( + map((dpop: DPoPHeaders) => req.clone({ + setHeaders: { ...dpop } + })), + switchMap((request) => next(request)) + ); +}; +``` + +Now, if you sign in and call the Users API, you'll get the list of users in your Okta org using DPoP. + +## Manually request DPoP-protected resources + +Earlier, we pretended to steal the access token to make other resource requests. You called the Okta Apps API using a JWT token to see the list of all the apps your Okta org contains. What happens if we try this again when the API requires DPoP? + +In DevTools, open the **Network** tab and find the `/users` call. You need both the proof and the access token for your HTTP call. Make an HTTP request: + +```curl +curl -v --header "Authorization: DPoP {yourAccessToken}" --header "DPoP: {yourDPoPProof}" https://{yourOktaDomain}/api/v1/apps +``` + +The API rejected your request! You get back an error stating the DPoP proof isn't valid: + +```http +HTTP/1.1 400 Bad Request +WWW-Authenticate: DPoP algs="RS256 RS384 RS512 ES256 ES384 ES512", authorization_uri="http://{yourOktaDomain}/oauth2/v1/authorize", realm="http://{yourOktaDomain}", scope="okta.apps.read", error="invalid_dpop_proof", error_description="'htu' claim in the DPoP proof JWT is invalid." +``` + +If an attacker manages to capture both the proof and the token, they may only be able to make the same request. The proof constrains the calls to the HTTP method and URI, invalidating other HTTP requests. + +How about making the same request? + + +```curl +curl -v --header "Authorization: DPoP {yourAccessToken}" --header "DPoP: {yourDPoPProof}" https://{yourOktaDomain}/api/v1/users +``` + +The API rejected your request! You still get back an error stating the DPoP proof isn't valid: + +```http +HTTP/1.1 400 Bad Request +WWW-Authenticate: DPoP algs="RS256 RS384 RS512 ES256 ES384 ES512", authorization_uri="http://{yourOktaDomain}/oauth2/v1/authorize", realm="http://{yourOktaDomain}", scope="okta.users.read.self", error="invalid_dpop_proof", error_description="The DPoP proof JWT has already been used.", resource="/api/v1/users" +``` + +The proof also has two other protection mechanisms: the JWT unique identifier (`jit`) and the issued at time (`iat`). When a resource server enforces the `jit` claim, it tracks previous calls to prevent proof reuse. So, an attacker can't replay the proof and the access token they stole. Enforcing the JWT ID isn't required in the DPoP spec. Another protection mechanism is the proof issue timestamp, the `iat` claim. Resource servers check the issue time on the proofs, and if it exceeds some threshold determined by the resource server, the server will reject the request. + +## Store cryptographic keys in browser applications + +We must securely store the keyset within the SPA and prevent an attacker from exfiltrating them. If an attacker has the keyset, they can impersonate you and make DPoP-protected calls. Fortunately, Okta SDK uses a few different techniques to mitigate keyset hijacking without any extra coding on your part. + +Local and session storage aren't secure enough; this time, we'll rely on [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) storage. The typical use case for IndexedDB is storing a large volume of data, but it has some built-in security mechanisms that work well for protecting the keyset. The `SubtleCrypto` API supports generating non-exportable keys, preventing browser code from turning the private key into a portable format. IndexedDB stores the keys as a `CryptoKeyPairs` object and DB query results return a reference to the object, not the raw key. IndexedDB protects sensitive private keys but still works with the `WebCrypto` methods for signing proof. + +You can inspect the keys by following the steps: + 1. Navigate to the **Applications** tab in DevTools + 2. Expand **IndexedDB** under the **Storage** sidenav + 3. Expand **OktaAuthJs** > **DPoPKeys** + +The downside is that the IndexedDB API is more difficult to use than other browser storage APIs. Because IndexedDB data persists, we must clean up the keys when done manually. The SDK handles cleanup if the user explicitly signs out, but we can't guarantee a user always will. We can clear keys before signing in. + +Open `src/app/app.component.ts` to find the `signIn()` method. + +> **React and Vue project instructions** +> +> Find the code where the project calls the `signInWithRedirect()` method and follow the instructions described for Angular projects. + +Add the call to clear keys as the first step in the `signIn()` method: + +```ts +public async signIn() : Promise { + await this.oktaAuth.clearDPoPStorage(true); + await this.oktaAuth.signInWithRedirect(); +} +``` + +## Use modern evergreen browsers for secure token handling + +Creating and storing cryptographic keys in JavaScript apps requires a capable browser. Modern, evergreen browsers have the API support required for DPoP. Check browser capability if your app supports users who use less modern, more questionable browsers. The Auth JS SDK has a method to check browser capability, `authClient.features.isDPoPSupported()`. You can add this check during application bootstrapping or initialization. + +Remember, even if you aren't using DPoP, modern browsers have more built-in security mechanisms. Stay secure, stay updated, and use safe browser practices whenever possible. + +## Learn more about web security, DPoP, and OAuth 2.0 + +In this post, you applied DPoP to a SPA and inspected DPoP in action. I hope you enjoyed it! If you want to learn more about the ways you can incorporate authentication and authorization security in your apps, you might want to check out these resources: + +* [OAuth 2.0 and OpenID Connect overview](https://developer.okta.com/docs/concepts/oauth-openid/) +* [The Identity of OAuth Public Clients](/blog/2022/06/01/oauth-public-client-identity) +* [Add Step-up Authentication Using Angular and NestJS](/blog/2024/03/12/stepup-authentication) +* [Configure OAuth 2.0 Demonstrating Proof-of-Possession](https://developer.okta.com/docs/guides/dpop/-/main/) + +Remember to follow us on [Twitter](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/c/OktaDev/) for more exciting content. We also want to hear from you about topics you want to see and questions you may have. Leave us a comment below! diff --git a/_source/_posts/2024-09-26-oktane-saas-developers.md b/_source/_posts/2024-09-26-oktane-saas-developers.md new file mode 100644 index 0000000000..51cea70661 --- /dev/null +++ b/_source/_posts/2024-09-26-oktane-saas-developers.md @@ -0,0 +1,62 @@ +--- +layout: blog_post +title: "Propel Your SaaS Apps Into the Future at Oktane" +author: [michael-palermo, jeff-taylor] +by: advocate +communities: [devops,security,mobile,.net,java,javascript,go,php,python,ruby] +description: "See you at Oktane in Las Vegas on October 15-17, 2024. We have activities, experiences, and labs with developers in mind." +tags: [announcement, conference] +image: blog/oktane-saas-developers/social.jpg +type: awareness +--- + +We've been discussing and reflecting on the Future of Identity over the last couple of months. It's apparent to us that Identity is rapidly growing in its complexity. The surface area that our customers need to protect is growing, like a sunrise revealing a hidden terrain in the morning twilight. We realize that in a short time, the **growing demands of customers will start to influence the roadmaps of SaaS companies and their developers to keep pace with protecting their customers and differentiating their value in their respective markets.** The timing of this discussion couldn't be better! We would love to meet you, hear about your vision and challenges, and nerd out on Identity and Software Development. Join us at Caesars Forum in Las Vegas, NV, on October 15-17, 2024, for [Oktane](https://www.okta.com/oktane), the biggest identity event of the year, and learn how to propel your SaaS apps into the future by connecting with Okta! + +> If you are currently not attending Oktane (but would like to) and you build SaaS apps, please reach out to us at wic-dev-advocacy[at]okta.com to request information regarding how you can obtain a pass. Limited number of passes available so reach out soon! + +We planned fantastic events to help you take your SaaS apps to the next level by leveraging Okta's identity and user lifecycle platforms. Find us and let's chat at these activities: + +## Breakout sessions + +**Building a SaaS Application with CIC**
    +Wednesday Oct 16, 3:45 PM + +**Empower your Ecosystem with Okta**
    +Thursday Oct 17, 12:45 PM + +**B2B SaaS App of the Future**
    +Thursday Oct 17, 2:30 PM + + +## Stop by the Oktane Dev Hub + +Take a drive through the Oktane Expo Hall, and you'll find the SaaS B2B experience in the Dev Hub at the intersection of SaaS Way and Integration Drive. Here, you'll discover the ways Okta can help you create secure B2B SaaS applications. You'll learn about identity and user lifecycle management best practices. Then build these standards-compliant solutions into your apps so you can submit them to the [Okta Integration Network](https://www.okta.com/okta-integration-network/) (OIN) and watch your customer base grow! + +## Check out the Oktane Hands-on Labs for interactive learning opportunities + +Roll up your sleeves and get your coding on. This is your chance to get techy and build code using Okta solutions. Find us at labs where you can pick from options such as: + +**Scaling Okta App Management by Importing Data from PowerShell into Terraform**
    +Streamline and scale your Okta app management by using PowerShell to export configurations and use Terraform to automate environment transitions. + +**Universal Logout: Instantly Sign a User Out across All Your Apps**
    +Learn how to lock down all your apps and protect your customers completely at the first sign of trouble with one API! + +**Identify Inactive Okta Users with Okta Workflows**
    +Determine if you have unused accounts that might have been missed by some manual deprovisioning process. + +Labs are first-come-first-serve and have limited capacity. If there's a lab you're interested in, be sure to show up on time! + +## B2B SaaS builders happy hour + +Join us at a special event for those who build apps that connect with Okta for their customer base! This happy hour is where all the fun and connections happen. This is a private event exclusively for techy folk who build multi-tenant B2B SaaS applications and want to offer Okta Identity Provider connections as an option for their customers. Does this describe you and are you interested in attending this event? Please contact us at wic-dev-advocacy[at]okta.com to be added to our guest list. You must be an attendee at Oktane to attend this happy hour. + +## Okta Workflows community meetup + +Join the [Okta Workflows community meetup](https://www.meetup.com/okta-workflows/events/303467311) during Oktane 2024 in Las Vegas. Meet Workflows community members, colleagues, and friends over drinks and delicious appetizers. + +## Find resources, solutions, and networking opportunities at Oktane + +We're excited to connect with you and learn about your application's needs! Please find us at Oktane, and feel free to comment if you have any questions or requests in the meantime. + +Remember to follow us on [Twitter](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/c/OktaDev/) for exciting content. diff --git a/_source/_posts/2024-10-11-terraform-ci-cd.md b/_source/_posts/2024-10-11-terraform-ci-cd.md new file mode 100644 index 0000000000..107e7fb427 --- /dev/null +++ b/_source/_posts/2024-10-11-terraform-ci-cd.md @@ -0,0 +1,501 @@ +--- +layout: blog_post +title: "How to Create a Secure CI/CD Pipeline Using Okta Terraform" +author: nick-connelly +by: internal-contributor +communities: [devops] +description: "Learn how to create a secure CI/CD pipeline with the power of Okta Terraform!" +tags: [terraform, ci, cd, aws] +image: blog/terraform-ci-cd/social.jpg +type: conversion +github: https://github.com/oktadev/okta-terraform-devops-template-example +--- + +Embarking on a DevOps journey can be exciting and daunting, especially for beginners. The landscape is vast, and the learning curve can feel steep. One of the most common challenges is setting up and managing a robust Continuous Integration/Continuous Deployment (CI/CD) pipeline that ensures seamless integration and delivery of code changes. This guide aims to simplify that process by walking you through setting up a CI/CD pipeline for Okta using Terraform, AWS, and GitHub Actions. + +## Overcoming DevOps challenges securely + +Getting started with DevOps often presents a series of challenges: +1. **Running Locally**: Setting up Terraform locally involves dealing with packages, dependencies, and managing the state file, which can be cumbersome and error-prone. +2. **Collaboration**: Ensuring team members can collaborate effectively requires a consistent and reproducible environment. + +Making a setup production-ready introduces further complexities: + +1. **State File Storage**: Knowing where and how to store the Terraform state file securely. +2. **Secrets Management**: Safely storing and managing sensitive information like API keys and passwords. +3. **Automation**: Automating the deployment process to ensure reliability and efficiency. + +In this post, we'll use Okta, Terraform, AWS, GitHub, and GitHub actions to create a secure CI/CD pipeline. + +**Table of Contents**{: .hide } +* Table of Contents +{:toc} + +By the end of this post, you'll have a solid understanding of how to set up a CI/CD pipeline tailored for Okta and the knowledge to start implementing infrastructure as code with Terraform. + +Let's dive in and take the first step towards mastering DevOps with a practical, hands-on approach! + +**Prerequisites** + +You'll need the following tools installed on your local machine. Follow the installation instructions through the provided links. + * IDE with a Terraform plugin, such as [Visual Studio Code](https://code.visualstudio.com/) or [IntelliJ IDEA](https://www.jetbrains.com/idea/) + > Choosing the proper Integrated Development Environment (IDE) with a Terraform plugin is crucial for an efficient and error-free workflow. Some essential features to look for in your IDE: + > + > 1. **Variable Declaration Warnings**: If your Terraform module requires certain variables, the IDE will alert you when any required variables are not declared. + > 2. **Resource Declaration Assistance**: When you declare a resource, the IDE will warn you if any required attributes are missing and suggest attributes to add. + > 3. **Resource and Attribute Autocompletion**: The IDE will autocomplete resource names and attributes when referencing other resources, saving time and reducing errors. + + * [Git](https://git-scm.com/) + * Terminal window + +You'll need the following accounts: +* [Okta Workforce Identity Cloud Developer Edition account](https://developer.okta.com/signup/) +* [GitHub account](https://github.com/) and a [GitHub organization account](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) (You can create a free GitHub organization if you don't have access to one) +* A free [AWS account](https://signin.aws.amazon.com/signup?request_type=register) + +## CI/CD pipeline architecture using Terraform, AWS, Okta, and GitHub + +It is essential to understand the key components and their roles in the CI/CD process. This integration of GitHub, Terraform, AWS, and Okta allows for secure and efficient infrastructure management and deployment. The following overview details each component and its function. + +{% img blog/terraform-ci-cd/architecture-overview.jpg alt:"The developer creates code that interacts with GitHub which triggers workflows in GitHub Actions. A GitHub action starts GitHub OIDC IdP interactions with AWS to create roles and temporary credentials. GitHub Actions then triggers Terraform to use AWS resources to capture state and secrets and then calls Okta to create resources." width:"800" %} + +**User** + * **Develop Code**: Develops Terraform code on their local machine using a preferred IDE. Uses Git to push code to the GitHub repository. + +**GitHub Repository** +* **Code Storage**: Stores the Terraform configuration code. +* **Triggers Workflow**: GitHub Actions checks out code that automates builds using Terraform based on events within the GitHub repository (e.g., push to branches, pull requests, etc.). + +**GitHub Actions** +* **Workflows**: Workflows are automatically triggered by GitHub repository events and execute the necessary commands to integrate with AWS and Terraform. +* **AWS**: + * **Assume Role**: Integrates with AWS IAM STS via GitHub OIDC IdP to authenticate and assume roles with web identity. + * **Temporary Credentials**: Utilizes temporary credentials returned from AWS IAM STS for Terraform backend operations. +* **Terraform**: Runs Terraform commands to manage infrastructure. + +**Terraform** +* **State Management**: + * **S3**: Utilizes S3 for storing Terraform state files. + * **DynamoDB**: Uses DynamoDB for state locking to ensure consistency and prevent concurrent operations. + * **Secrets Management**: Retrieves Okta OAuth2 client credentials private key from AWS Secrets Manager for authentication and authorization to Okta management APIs. +* **Okta**: + * **Resource Management**: Leverages Okta APIs via the Terraform Okta provider to manage resources. + +## CI/CD workflow overview + +At a high level, this is what we aim to build out through this article. We'll set up a CI/CD pipeline that automates infrastructure deployment using GitHub, Terraform, AWS, and Okta. Here's a simplified overview of the workflow: + +{% img blog/terraform-ci-cd/workflow.jpg alt:"There are two Git branches: main and develop. A commit to the develop branch triggers the GitHub Action to build, then creates a pull request to main. The GitHub action also creates a production plan and merges develop into main. The GitHub action then builds prod." width:"800" %} + +1. **Branch Creation**: Developers create and work on a `develop` branch. +2. **Push to Develop**: Code changes are committed locally and pushed to the remote `develop` branch. +3. **Dev Build**: GitHub Actions run Terraform commands to deploy to the development environment. The push to develop automatically triggers this. +4. **Pull Request to Main**: A pull request is made from `develop` to `main` for code review. Any GitHub Action workflow executions are included in the pull request for review. +5. **Prod Plan**: GitHub Actions preview changes for the production environment. This is triggered automatically by the pull request to main, and it lets pull request reviewers validate potential changes before modifying the production environment. +6. **Merge to Main**: The pull request is approved and merged into the `main` branch. +7. **Prod Build**: GitHub Actions runs Terraform commands to deploy to the production environment. The merge to `main` automatically triggers this. + +## Store Terraform files in source control + +We'll use GitHub as our code repository and GitHub Actions for our CI/CD workflows, so you'll need a GitHub account. If you don't have one, create one at [GitHub](https://github.com/). + +You will also need a GitHub Organization. If you are an enterprise user, you likely already have one. If not, or if you're experimenting, you can create one for free by following the [GitHub Organizations](https://github.com/settings/organizations) instructions to start creating an Organization. + +You'll create a new repository within your GitHub Organization and then connect it to your local development environment: + +1. **Create a new repository**: We created a templated repository for you to use for this guide. Follow the [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) instruction from GitHub and use this [sample template](https://github.com/oktadev/okta-terraform-devops-template-example). Select your GitHub Organization as the owner and name the repository using a structure such as `{okta-domain-name}-okta-terraform` (e.g., `atko-okta-terraform`). Ensure you set the repository to **Private**. This setting is crucial as the repository will run GitHub Actions workflows and have information related to your environment (e.g., AWS resource names). +2. **Clone the Repository**: Once you create your repository, copy the clone link and run the following commands in the command line. Replace the variables with your GitHub username, GitHub organization, and repository name: +```bash +git clone https://{your_github_username}@github.com/{your-github-organization}/{your-repository-name}.git +cd {your-repository-name} +``` + +## Connect to Okta securely using OAuth 2.0 + +We will use the OAuth 2.0 client credentials flow to access Okta APIs. OAuth 2.0 is the most secure method for integrating with Okta APIs, as we can tightly bound authorizations using scopes, and access tokens are short-lived compared to the long-lived `SSWS` API keys. Furthermore, Okta's Terraform provider supports [OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)](/blog/2024/09/05/dpop-oauth), which is an additional security mechanism to bind access tokens to a particular client through cryptography, thereby reducing the risk of token replay by a malicious actor. + +The Okta OAuth client requires 'scopes' to interact with the management API. For this guide, we will interact with the Groups resource in Terraform and corresponding APIs. To understand the corresponding scopes related to a Terraform resource and underlying Management APIs, refer to the [Okta API documentation](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/). + +Finally, the OAuth client requires an Administrator Role to make administrative changes. We will assign the Organization Administrator role as this contains sufficient permissions for the resources we manage within this build. If you intend to use Terraform to manage your environment ongoing, a Super Administrator may be required (especially for managing resources like Admin Roles). The effective permissions are a combination of the scopes permitted for the client and the Administrator Role - so even though we provide the client 'Organization Administrator,' if we only give access to 'groups' related scopes, all the client can do via the API is manage groups! + +Follow these steps to set up an API Services application in Okta. Navigate to the [Okta Admin Console](https://developer.okta.com/login/) and follow the steps to create the API services application: + 1. Navigate to **Applications** > **Applications** and press the button to **Create App Integration** + 2. Select **API Services** and press **Next** + 3. Name your application (e.g., Terraform) + 3. Press **Save** + +In the **General Settings** tab, find the **Client Credentials** section and press **Edit** to make the following changes: + 1. Change the **Client authentication** method to **Public key / Private key**. + 2. In the **Public Keys** section, click **Add key** and then **Generate new key**. + 3. Select the **PEM** tab and copy the contents to a file you'll use later. + 4. Select **Done** and **Save** + +Navigate to **Okta API Scopes** tab and make the changes: + 1. Find `okta.groups.manage` and select **Grant** + +Navigate to the **Admin roles** tab and press **Edit assignments**. Then apply the following changes: + 1. In the **Role** drop-down, select 'Organization Administrator', or your preferred Admin Role + 2. Select **Save Changes** to finish assigning the role + +Repeat these steps to create an API Service Okta application and configure it for any additional environments you manage. + +> ⚠️ **Important** +> +> Do not save the private key locally. In the next steps, we will securely onboard it to secrets management. + +## Leveraging AWS for Terraform Backend and Secrets Management + +We will utilize AWS for both the Terraform backend and Secrets Management. The Terraform backend will store state files, which track the status of your Okta environment based on previous builds. We will use the GitHub OIDC integration with AWS for Terraform authentication. This allows GitHub to authenticate with AWS using OpenID Connect (OIDC) and assume the necessary role via web identity to interact with required services. This approach eliminates the need for long-lived or persistent secrets (such as AWS access keys and secrets), ensuring a more secure setup. + +### Store Terraform backend components in AWS + +First, let's create the necessary components for the Terraform backend. + +**Create an S3 Bucket** + +Follow the [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) instructions from AWS to create a bucket. Name the bucket using a structure such as `{okta-domain-name}-okta-terraform-state`. By default, **Block all public access** is enabled, which ensures that your bucket contents are private, which is an integral control given that the bucket will contain information about your Okta configuration. I highly recommend enabling **Bucket Versioning** to version your state files. This is a valuable feature should you need to roll back to previous versions of the state. After you have created the bucket, follow the [Viewing the properties for an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/view-bucket-properties.html) instructions to navigate to the properties of the bucket and capture the ARN. The ARN will be used later to define the AWS IAM Role Policy. Lastly, we will use folders to organize your different environments' state files. Follow the [Organizing objects in the Amazon S3 console by using folders](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-folders.html) instructions to create a folder for each environment you manage (e.g. dev and prod). + +**Create a DynamoDB Table for State Locking** + +Follow the [Create a table in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html) instructions to create a DynamoDB table. Name the table using a structure such as `{okta-domain-name}-okta-terraform-{environment}` (e.g. `atko-okta-terraform-dev`). Set the partition key to 'LockID' and leave other configuration defaults. Note the table name, we will be using it later in the AWS IAM Role Policy definition. Repeat for any other environments you manage. + +For more information on the AWS S3 Terraform backend, please refer to [Terraform S3 Backend Documentation](https://developer.hashicorp.com/terraform/language/settings/backends/s3). + +### Manage secrets securely + +Next, we will set up AWS Secrets Manager to securely store the private key for authentication and authorization to Okta management APIs. + +Follow the [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) instructions to store the OAuth 2.0 private key(s). When configuring the secret, note this is of the secret type **Other type of secret**, and **Plaintext**. Ensure you name the secret something meaningful, as this will be referenced in your Terraform configurations, as well as AWS IAM Role Policy definition - follow a structure such as `{environment}/okta-terraform-key` (e.g., `dev/okta-terraform-key`). Since it's a private key, keep any rotation-related configurations as default options. Once the secret has been created, copy the ARN for later use within the AWS IAM Role Policy definition. Repeat for any additional environments you manage. + +### Set up the IAM policy for the CI/CD pipeline + +Next, we'll create the IAM Policy definition. This policy will be used by the role that GitHub will assume via OpenID Connect (OIDC). + +First, we will prepare the IAM policy JSON file. +Use the following template and make the necessary replacements using the ARNs you've captured from the previous steps. + * Replace `` with the ARN of your S3 bucket. This grants permission to list the bucket. You can find it under the **Properties** tab of the S3 Bucket. Example: `arn:aws:s3:::akto-okta-terraform` + * Replace `/*` with the ARN of your S3 bucket and any folder structures for respective environments. This grants permission to get and update objects in the relevant path. Alternatively, you can use a wildcard (`*`) for the entire bucket. Example: `arn:aws:s3:::akto-okta-terraform/dev/*` + * Replace ``, ``, and `` with the AWS Region, AWS Account Number (found in the management console toolbar) and DynamoDB Table Name respectively. This grants permission to add and remove rows in the table for the Terraform state file locking process. Include any additional tables for each environment. + `Example: arn:aws:dynamodb:ap-southeast-2:99123456789:table/akto-okta-terraform-dev` + * Replace `` with the ARN of your Secrets Manager secret. This grants permission to retrieve the secret value. Include any additional ARNs for each environment. + Example: `arn:aws:secretsmanager:ap-southeast-2:99123456789:secret:dev/akto_okta_terraform_key-QuqiGR` + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:ListBucket", + "Resource": "" + }, + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject" + ], + "Resource": [ + "/*" + ] + }, + { + "Effect": "Allow", + "Action": [ + "dynamodb:DescribeTable", + "dynamodb:GetItem", + "dynamodb:PutItem", + "dynamodb:DeleteItem" + ], + "Resource": [ + "arn:aws:dynamodb:::table/" + ] + }, + { + "Effect": "Allow", + "Action": [ + "secretsmanager:ListSecrets", + "secretsmanager:GetSecretValue" + ], + "Resource": [ + "" + ] + } + ] +} +``` + +Follow the [Create IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) documentation for instructions on creating an IAM Policy. When creating the policy document, use the JSON editor and input the JSON from the previous step. Name the policy something meaningful (e.g. 'Okta_Terraform_Backend'). + +By following these steps, you will have created an IAM policy that provides the necessary permissions for Terraform to interact securely with AWS services. + +### Configure an OpenID Connect Provider in GitHub + +Next, we'll configure the OIDC Identity Provider for GitHub. Follow the AWS instructions at [Create an OpenID Connect identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-console). + + * For the **Provider URL**, use `https://token.actions.githubusercontent.com` + * For the **Audience**, use `sts.amazonaws.com` + +For more information on integrating GitHub with AWS using OIDC, refer to the [GitHub and AWS integration documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services). + +### Create IAM roles for the CI/CD pipeline + +Finally, we'll create an IAM Role for the GitHub OIDC Identity Provider to assume. This role will link the OIDC Identity Provider via the trusted entity and the policy via permissions. + +Follow the instructions for [Creating a role for OIDC](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create) from AWS. +When configuring the Trusted Entity, choose **Web Identity**, and use the following values for the configurations: + * **Identity provider**: `token.actions.githubusercontent.com` + * **Audience**: `sts.amazonaws.com` + * **GitHub organization**: `{your_github_organization}` (the unique identifier for your GitHub Organization) + * **GitHub repository**: `{your_github_repository}` (the name of your GitHub repository) + + +For permissions, choose the IAM Policy ('Okta_Terraform_Backend', or your name of choosing) you created earlier. Name the role something meaningful (e.g. 'GitHub_Okta_Terraform_Backend'). Once the role has been created, copy the Role ARN. This is the only variable we need to pass to our pipeline to initialize the backend and retrieve the secret to authenticate and authorize Okta APIs — and it's not even a secret! + +By following these steps, you will have created an IAM Role that GitHub can assume via OIDC, enabling secure interactions with AWS and Okta. + +## Use GitHub Actions to trigger Terraform commands + +GitHub Actions allows us to run our build and deployment activities using Terraform commands executed in a temporary virtual machine. + +First, we must store the Role ARN and other environment variables in GitHub. To create and store variables for the GitHub repository, follow the [Creating configuration variables for a repository](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) instructions. + +1. **Store the Role ARN**: Create a variable named AWS_ROLE_ARN and use the Role ARN for the value (e.g. `arn:aws:iam:::role/`). +1. **Store the Region**: Create a variable named AWS_REGION and use the Region in which the AWS resources were created (e.g. `ap-southeast-2`). Refer to the following documentation for more details on Region names: [AWS Regions Documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) + +> Ensure you do this at a 'Repository' level and not at an 'Organization' level, or the GitHub Actions workflows will not be able to read the variables + +### Leverage GitHub Actions for the CI/CD workflow + +We will use multiple pre-built GitHub Actions to authenticate to AWS and run our Terraform commands. No action is required from you to configure these workflows. At a high level, the configured GitHub Actions workflows will perform the following: + +1. **GitHub Actions Runner**: This action checks out your repository onto the runner, allowing you to run Terraform commands against your code. +1. **AWS Configure AWS Credentials**: This action establishes an AWS session using the GitHub OIDC Identity Provider (IdP) and the Assume Role with Web Identity capability. There is no need to manage any secrets or custom scripts, as this action will handle session establishment. +1. **Terraform CLI**: This action runs the Terraform commands. + +For more information and to examine the code, see the `github/workflows` folder within the repository. + +### Organize the CI/CD and Terraform code files for maintainability + +The high-level structure of the repository looks like this: + +```markup +github/ +├─ workflows/ +│ ├─ push-main.yml +│ ├─ push-develop.yml +│ ├─ pr-main.yml +terraform/ +├─ modules/ +│ ├─ {module}/ +│ │ ├─ {resource}.tf +│ │ ├─ variables.tf +├─ main.tf +├─ variables.tf +├─ backend-dev.conf +├─ backend-prod.conf +├─ vars-dev.tfvars +├─ vars-prod.tfvars +``` + +#### Review the GitHub Workflows directory + +* **github/workflows/**: This directory contains the GitHub Actions workflow files that define the CI/CD pipeline. + * **push-main.yml**: Workflow triggered by a push to the main branch. + * **push-develop.yml**: Workflow triggered by a push to the develop branch. + * **pr-main.yml**: Workflow triggered by a pull request to the main branch. + +#### Review the Terraform configuration files + +* **terraform/**: The root directory for all Terraform configuration files. + * **modules/**: This directory contains reusable Terraform modules. + * **{module}/**: Each module has its own directory. + * **{resource}.tf**: The Terraform configuration file for specific resources within the module. + * **variables.tf**: The child module input variables definition file + * **main.tf**: The main Terraform configuration file where all providers, modules, and variables are configured. + * **variables.tf**: The parent module input variables definition file. + * **backend-dev.conf**: Configuration for the backend components for the development environment. This configuration must be passed in via CLI since named variables cannot be used directly in the backend block. + * **backend-prod.conf**: This is the configuration for the backend components in the production environment, similar to the development configuration. + * **vars-dev.tfvars**: Input variable values specific to the development environment. + * **vars-prod.tfvars**: Input variable values specific to the production environment. + +## Build the CI/CD pipeline using Terraform and Okta + +Now that we have everything set up, let's actually build something! + +First, we will need to update a few files with some of the necessary configurations relevant to your environment. Then we will create a new group in your Okta environment, using variables to declare the group name. + +### Set up source control branches for Terraform code files + +Ensure your local repository is up-to-date with the remote main branch. + +```bash +git checkout main +git pull origin main +``` + +Create and switch to the branch named develop. + +```bash +git checkout -b develop +``` + +### Finalize Terraform configuration + +Now that we have checked out our code let's finalize the configurations required for Terraform to interact with our backend, retrieve the necessary secrets, and interact with the Okta Management APIs. Open the repository in your preferred IDE to edit some files. + +#### Backend configuration files + +The Terraform backend configuration is stored within the `backend-*.conf` files and contain configurations relevant to your environments. Within these files, you will find placeholders for the following: + * `bucket` - the name of your bucket (not the ARN!) + * `key` - the path to your Terraform state file (i.e. the folder and resultant file name, which defaults to `terraform.tfstate`) + * `dynamodb_table` - the name of your DynamoDB table (not the ARN!) + * `region` - the AWS Region + +Replace all the placeholders in the `backend-*.conf` files. There are two placeholders for development and production environments, respectively. Refer to the following example as a reference: + +``` +bucket = "atko-okta-terraform" +key = "dev/terraform.tfstate" +dynamodb_table = "atko-okta-terraform-dev" +region = "ap-southeast-2" +``` + +#### Terraform variables (tfvars) + +Variables are a critical component within the infrastructure as code configurations allow you to have a single set of configurations while maintaining environment-specific values. Within Terraform, one way to manage such environment-specific values is using 'tfvars' files. The 'tfvars' file contains a set of variable values specific to an environment. It is passed in via the Terraform CLI in our GitHub Actions workflow when running specific parts of the workflow. + +Additional configuration-related variables stored within the `vars-*.tfvars` files require updates. Within these files, you'll find placeholders for the following: + * `region` - the AWS Region + * `okta_org_name` - the prefix value for your Okta tenant + * `okta_base_url` - the base or suffix value for your Okta tenant + * `okta_scopes` - the scopes for the Terraform Okta OAuth 2.0 client application + * `okta_client_id` - the client ID for the Terraform Okta OAuth 2.0 client application + * `okta_private_key_id` - the private key ID for the Terraform Okta OAuth 2.0 client application. This is the 'KID' value, which can be obtained in the 'Public Keys' section of the OAuth 2.0 application configuration + * `okta_secret_id` - the AWS Secrets Manager 'secret name' for the private key of the Terraform Okta OAuth 2.0 client application. This is the 'Secret name' value, not the 'Secret ARN'. + +Replace all the placeholders in the `vars-*.tfvars` files. Refer to the following example as a reference: +``` +region = "ap-southeast-2" +okta_org_name = "atko" +okta_base_url = "oktapreview.com" +okta_scopes = [ + "okta.groups.manage" +] +okta_client_id = "0oaes123y1FekjfoE1d7" +okta_private_key_id = "ievOgRgNc...aJJn5ra_4" +okta_secret_id = "dev/okta_terraform_key" +``` + +### Connect Terraform code to Okta resources + +The repository includes a directory module containing a resource okta_groups.tf, which we will use to provide a group for your Okta tenant. In doing so, we'll also go through a core tenet of the previously mentioned variables, where we will define both input and output variables. This may be a little confusing initially, so take some time to understand how the different files and modules interact! The following diagram may help contextualize the various files we are going to step through: + +{% img blog/terraform-ci-cd/module-files.jpg alt:"The parent module contains tfvars, which contains variable values that lead to main.ts. This then has reference variables which lead " width:"800" %} + +Open `terraform/modules/directory/variables.tf` and uncomment the following entry. This is the variables file for the directory module and it defines which input variables are required. Each module you develop will have its own variables file. + +```tf +variable "okta_group_name" { + type = string +} +``` + +Open `terraform/modules/directory/okta_groups.tf` and uncomment the following entry. This is a resource block. The resource block has two parts: firstly, the resource type, `okta_group` , and the resource name, `okta_test_group`. Feel free to change the resource block name (okta_test_group) to something you choose. Within the resource block body are the configuration arguments for the resource. We have one argument defined, which is the name, referencing the input variable okta_group_name + +```tf +resource "okta_group" "okta_test_group" { + name = var.okta_group_name +} +``` + +Open `terraform/variables.tf` and uncomment the following entry. This is the variables file for the parent or main module. The variables within this file are assigned via the `tfvars` files, which are passed in with environment-specific configurations via the Terraform CLI: + +```tf +variable "okta_group_name" { + type = string +} +``` + +Next, open `terraform/main.tf` and uncomment the following entry. The main file contains critical configurations for the backend and providers (like Okta or AWS). It also is where we reference any modules, including the directory module, via their path within the local repository. It's also necessary to pass through any variables within this module block. You can manage variables in two ways: +1. Configure the variable values directly within the main file, which may be acceptable for any standardized or non-environment-specific variables +2. Reference the parent module variables file like we have done, so in this example: + +``` +okta_group_name = var.okta_group_name +``` + +Open `terraform/dev.tfvars` and `terraform/prod.tfvars` and uncomment the following entry. This sets the value of the okta_group_name variable for each respective environment. Feel free to change it and make the values environment-specific. + +``` +okta_group_name = "Okta Test Group GitHub Actions" +``` + +Now, we can stage our changes. Use `git add` to add the changes for the next commit. + +```bash +git add . +``` + +Lastly, commit the changes: + +```bash +git commit -m "Initial commit" +``` + +With the changes committed, we can now push your changes to the remote `develop` branch. + +```bash +git push origin develop +``` + +### GitHub Actions triggers Terraform dev build + +GitHub Actions is configured to trigger a build when changes are pushed to the `develop` branch. The workflow defined in the repository will: + * **Authenticate with AWS**: Use GitHub OIDC to assume the necessary role. + * **Run Terraform Commands**: Execute terraform init, terraform plan, and terraform apply to deploy changes to the development environment. + +Monitor the action in GitHub to ensure the build completes successfully, and check your Okta environment to observe the creation of the group using the name specified in the tfvars file. + +> If GitHub Actions has any errors, refer to the error message within the GitHub Actions workflow for further details. +> +> If you missed any configurations within the repository files (e.g., `backend-*.conf` or `vars-*.tfvars`), make the changes locally and perform the `git add`, `git commit`, and `git push` commands again. +> +> If you missed any configurations within Okta (e.g., OAuth 2.0 scopes) or AWS (e.g., IAM Role permissions, etc.), then correct the issue and re-run the GitHub Actions workflow from the GitHub Actions console on a failed workflow. + +Create a pull request to merge code from the `develop` branch to the `main` branch: + + * Navigate to the repository on GitHub. + * Open a pull request from `develop` to `main.` + * Provide a detailed description of the changes and any context or considerations for the reviewers. + +### GitHub Actions trigger Terraform prod plan + +When a pull request is opened, GitHub Actions triggers a Terraform plan for the production environment. This plan will: + * **Authenticate with AWS**: Use GitHub OIDC to assume the necessary role. + * **Run Terraform Plan**: Execute terraform init, terraform plan to show the potential changes without applying them against the production environment. + +Reviewers can inspect the planned output to understand the impact of the changes before merging. + +After reviewing and approving the pull request, merge it into the `main` branch. You can merge using the GitHub Pull Request user interface. + +### GitHub Actions trigger Terraform prod build + +Merging to the main branch triggers a new GitHub Actions workflow. The workflow will: + * **Authenticate with AWS**: Use GitHub OIDC to assume the necessary role. + * **Run Terraform Commands**: Execute terraform init, terraform plan, and terraform apply to deploy changes to the production environment. + +Monitor the Actions tab to ensure the deployment completes successfully. + +## Learn more about Okta, Terraform, CI/CD patterns, and OAuth 2.0 + +In this article, we have outlined the architecture and steps needed to set up a secure and efficient CI/CD pipeline using GitHub Actions, Terraform, AWS, and Okta. By leveraging these technologies, we can automate infrastructure management, ensuring consistency and reducing the risk of manual errors. We covered the integration of GitHub with AWS for secure authentication and authorization, the configuration of Terraform for state management and secrets handling, and the overall workflow for deploying changes from development to production. If you found this post interesting, you may like these resources: + +* [How to Secure Your Kubernetes Clusters With Best Practices](/blog/2021/12/02/k8s-security-best-practices) +* [How Can DevOps Engineers Use Okta?](/blog/2022/04/14/where-okta-meets-devops) +* [Store ASP.NET Secrets Securely with Azure KeyVault](/blog/2019/06/04/store-secrets-securely-int-dotnet-with-azure-keyvault) +* [How to Deploy a .NET Container with AWS ECS Fargate](/blog/2022/01/19/deploy-dotnet-container-aws-fargate) + +Stay tuned for subsequent articles for Okta recommended policies to help get you started with secure-by-design configurations from day one! + +Remember to follow us on [Twitter](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/c/OktaDev/) for more exciting content. Leave us a comment below if you have any questions or requests for topics! diff --git a/_source/_posts/2024-10-23-dpop-oauth-node.md b/_source/_posts/2024-10-23-dpop-oauth-node.md new file mode 100644 index 0000000000..1309fa69a9 --- /dev/null +++ b/_source/_posts/2024-10-23-dpop-oauth-node.md @@ -0,0 +1,440 @@ +--- +layout: blog_post +title: "How to Build Secure Okta Node.js Integrations with DPoP" +author: ram-gandhi +by: internal-contributor +communities: [security, javascript] +description: "Learn how to securely call Okta APIs using a private key JWT in a Node.js service app, then migrate the app to use possession-proof tokens with DPoP." +tags: [oauth, node, authorization, dpop] +image: blog/dpop-oauth-node/social.jpg +type: conversion +github: https://github.com/oktadev/okta-node-dpop-example +--- + +Integrating with Okta management API endpoints might be a good idea if you are trying to read or manage Okta resources programmatically. This blog demonstrates how to securely set up a node application to interact with Okta management API endpoints using a service app. + +Okta API management endpoints can be accessed using an access token issued by the Okta org authorization server with the appropriate scopes needed to make an API call. This can be either through authorization code flow for the user as principal or client credentials flow for a service as principal. + +For this blog, we will examine the OAuth 2.0 client credentials flow. Okta requires the `private_key_jwt` token endpoint authentication type for this flow. Access tokens generated by the Okta org authorization server expire in one hour. Any client can call Okta API endpoints with the token during this hour. + +## How do you make OAuth 2.0 access tokens more secure? + +Increase security by constraining the token to the sender. By constraining the token sender, the resource server knows every request originates from the original client that initially requested the token. OAuth 2.0 Demonstrating Proof of Possession (DPoP) is a way to achieve this, as explained in [this rfc](https://datatracker.ietf.org/doc/html/rfc9449). You can read more about DPoP in this post: + +{% excerpt /blog/2024/09/05/dpop-oauth %} + +To demonstrate this, we will first set up a node application with a service app without requiring DPoP. Then, we'll add the DPoP constraint and make the necessary changes in our app to implement it. + +**Table of Contents**{: .hide } +* Table of Contents +{:toc} + +## Create a service app with OAuth 2.0 client credentials without DPoP + +**Prerequisites** + +You'll need the following tools: + * [Node.js](https://nodejs.org/en) v18 or greater + * IDE (I used [VS Code](https://code.visualstudio.com/)) + * Terminal window (I used the integrated terminal in VS Code) + +## Add OAuth 2.0 and OpenID Connect (OIDC) to your Node.js service application + +Before you begin, you'll need a free Okta developer edition account. Sign up for a free [Workforce Identity Cloud Developer Edition account](https://developer.okta.com/signup/) if you don't already have one. + +Open [your Okta dashboard](https://developer.okta.com/login/) in a browser. Navigate to **Applications** > **Applications**. Select **API Services** and press **Next**. Name your application and press **Save**. + +1. In the General tab, note the **Client ID** value and your Okta domain. You can find the Okta domain by expanding the settings menu in the toolbar. You need these values for your application configuration. +2. Press edit in the **Client Credentials** section and follow these steps: + 1. Change the **Client authentication** to `Public Key / Private Key` + 2. In the **PUBLIC KEYS** section, press the **Add key** button. Click **Generate new key** to have Okta generate a new key. Save the private key (in PEM format) in a file called `cc_private_key.pem` for later use. + 3. Press **Save** + +In *General Settings* section, press edit and make the following changes: + * Disable **Proof of possession** > **Require Demonstrating Proof of Possession (DPoP) header in token requests** + * Press **Save** + +Navigate to the **Okta API Scopes** tab and grant the `okta.users.read` scope. + +In the **Admin roles** tab, press **Edit assignments**. Find the `Read-only Administrator` in the **Role** selection menu, and press the **Save Changes** button. + +Those are all of the changes required in Okta until you re-enable DPoP. + +### Configure OAuth 2.0 in the Node.js service + +Create a project directory for local development named `okta-node-dpop`. Open the project directory in your IDE. Create a file called `.env` file to the project root directory and add the following configuration settings: + +``` +OKTA_ORG_URL=https://{yourOktaDomain} +OKTA_CLIENT_ID={yourClientID} +OKTA_SCOPES=okta.users.read +OKTA_CC_PRIVATE_KEY_FILE=./assets/cc_private_key.pem +``` + +Save the private key file from the earlier step as `assets/cc_private_key.pem` in the root directory. + +## Create an OAuth 2.0-compliant Node.js service app + +Open a terminal window in the project directory and run `npm init` to create the scaffolding. Press Enter to accept all defaults. + +Install dependencies for the project by running: + +```bash +npm i dotenv@16.4.5 jsonwebtoken@9.0.2 +``` + +Create an `oktaService.js` file in the project root. We'll add the basic foundation of authenticating and calling Okta endpoints in this file. This file contains three key functions: + + * `oktaService.authenticate(..)` method gets an access token by: + * Generating a private key JWT required for authenticating and signs it using a keypair registered in the Okta application + * Generating the token request to Okta org authorization server + * Retrieving and stores the access token for future calls + **Note** - This token is valid for one hour by default at the time of writing this article + * `oktaService.managementApiCall(..)` method makes the Okta management API calls and adds the necessary headers and tokens to enable the request + * `oktaHelper` contains utility methods to store okta configuration, access token, generating private key JWT, generating token request + +Add the following code to the `oktaService.js` file: + +```javascript +const fs = require("fs"); +const crypto = require("crypto"); +const jwt = require("jsonwebtoken"); +require("dotenv").config(); // Loads variables in .env file into the environment + +const oktaHelper = { + oktaDomain: process.env.OKTA_ORG_URL || "", // Okta domain URL + oktaClientId: process.env.OKTA_CLIENT_ID || "", // Client ID of API service app + oktaScopes: process.env.OKTA_SCOPES || "", // Scopes requested - Okta management API scopes + ccPrivateKeyFile: process.env.OKTA_CC_PRIVATE_KEY_FILE || "", // Private Key for signing Private key JWT + ccPrivateKey: null, + accessToken: "", + getTokenEndpoint: function () { + return `${this.oktaDomain}/oauth2/v1/token`; + }, // Token endpoint + getNewJti: function () { + return crypto.randomBytes(32).toString("hex"); + }, // Helper method to generate new identifier + generateCcToken: function () { + // Helper method to generate private key jwt + let privateKey = + this.ccPrivateKey || fs.readFileSync(this.ccPrivateKeyFile); + let signingOptions = { + algorithm: "RS256", + expiresIn: "5m", + audience: this.getTokenEndpoint(), + issuer: this.oktaClientId, + subject: this.oktaClientId, + }; + return jwt.sign({ jti: this.getNewJti() }, privateKey, signingOptions); + }, + tokenRequest: function (ccToken) { + // generate token request using client_credentials grant type + return fetch(this.getTokenEndpoint(), { + method: "POST", + headers: { + Accept: "application/json", + "Content-Type": "application/x-www-form-urlencoded", + }, + body: new URLSearchParams({ + grant_type: "client_credentials", + scope: this.oktaScopes, + client_assertion_type: + "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", + client_assertion: ccToken, + }), + }); + }, +}; + +const oktaService = { + authenticate: async function () { + // Use to authenticate and generate access token + if (!oktaHelper.accessToken) { + console.log("Valid access token not found. Retrieving new token...\n"); + let ccToken = oktaHelper.generateCcToken(); + console.log(`Using Private Key JWT: ${ccToken}\n`); + console.log(`Making token call to ${oktaHelper.getTokenEndpoint()}`); + let tokenResp = await oktaHelper.tokenRequest(ccToken); + let respBody = await tokenResp.json(); + oktaHelper.accessToken = respBody["access_token"]; + console.log( + `Successfully retrieved access token: ${oktaHelper.accessToken}\n` + ); + } + return oktaHelper.accessToken; + }, + managementApiCall: function (relativeUri, httpMethod, headers, body) { + // Construct Okta management API calls + let uri = `${oktaHelper.oktaDomain}${relativeUri}`; + let reqHeaders = { + Accept: "application/json", + Authorization: `Bearer ${oktaHelper.accessToken}`, + ...headers, + }; + return fetch(uri, { + method: httpMethod, + headers: reqHeaders, + body, + }); + }, +}; + +module.exports = oktaService; +``` + +Add a new file named `app.js` in the project root folder. This is the entry point for running our Node.js service application. In this file, we'll do the following: + + * Import `oktaService` + * Create an async wrapper to execute asynchronous code + * Authenticate to Okta by calling `oktaService.authenticate()` + * Validate the previous step by listing users using a `GET` call to Okta's `/api/v1/users` endpoint + +Paste the following code into the `app.js` file: +```javascript +const oktaService = require('./oktaService.js'); + +(async () => { + await oktaService.authenticate(); + + let usersResp = await oktaService.managementApiCall('/api/v1/users', 'GET'); + if(usersResp.status == 200) { + let respBody = await usersResp.json(); + console.log(`Users List: ${JSON.stringify(respBody)}\n`); + } else { + console.log('API error', usersResp); + } +})(); +``` + +Next, update this as the entry point. In the `package.json` file, update the `scripts` property with the following: + +```json +"scripts": { + "start": "node app.js" +} +``` + +This gives us an easy way to run the app. Run the app using `npm start`. You should see a list of console logs: + +```console +Valid access token not found. Retrieving new token... +Using Private Key JWT: eyJh........ +Making token call to https://........../oauth2/v1/token +Successfully retrieved access token: eyJ.................. +Users List: [.........] +``` + +If you receive any errors, this is a good time to troubleshoot and resolve issues before adding **DPoP**. + +## Secure access tokens by adding DPoP to the Node.js service + +Why isn't OAuth 2.0 client credential flow enough? + +Our setup used the `client_credentials` grant type to authenticate and get an access token. If someone gets hold of the private_key_jwt, they cannot replay it beyond expiration (I reduced it to 5 minutes to shorten this window). However, if someone gets ahold of the access token, they can use it for up to 1 hour, which is the default expiration time of an access token. + +Constraining the token sender is one way to make the access token more secure. How can you do that? By adding the Demonstrating Proof of Possession (DPoP) OAuth extension method to the access token interaction. The technique adds a sender-generated token for each call it makes. Doing so prevents replay attacks even before tokens expire since each call needs a fresh DPoP token. Here is the detailed flow: + +{% img blog/dpop-oauth-node/dpopflow.jpg alt:"Sequence diagram that displays the back and forth between the client, authorization server, and resource server for Demonstrating Proof-of-Possession" width:"800" %}{: .center-image } + +You'll enable DPoP in Okta application settings to experiment with sender-constrained tokens. Open the Okta Admin Console in your browser and navigate to **Application** > **Application** to see the list of Okta applications in your Okta account. Open the service application to edit it. + +In your service app's **General Settings** section, change **Proof of possession** > **Require Demonstrating Proof of Possession (DPoP) header in token requests** to `true`. Then click **Save**. + +You need a new public/private key pair to sign the DPoP proof JWT. If you know how to generate one, feel free to skip this step. I used the following steps to generate it: + * Go to [JWK generator](https://mkjwk.org/) + * Select the following and then click Generate. + * Key Use: Signature + * Algorithm: RS256 + * Key ID: SHA-256 + * Show X.509: Yes + * Copy the Public Key (JSON format) and save it to `assets/dpop_public_key.json` + * Copy the Private Key (X.509 PEM format) (**Do not click Copy to Clipboard. This will copy as a single line, which will not work with the following steps. Instead, copy the value manually and save it**) and save it to `assets/dpop_private_key.pem` + +Now that you have a new keypair for DPoP, you'll add the variables to the project. In the `.env` file, add the new file paths: + +``` +.... +OKTA_SCOPES=okta.users.read +OKTA_CC_PRIVATE_KEY_FILE=./assets/cc_private_key.pem +OKTA_DPOP_PRIVATE_KEY_FILE=./assets/dpop_private_key.pem +OKTA_DPOP_PUBLIC_KEY_FILE=./assets/dpop_public_key.json +``` + +Add the DPoP-related code to `oktaService.js`. Add the key files to config. We can use this while adding DPoP to our methods: + +```javascript +const oktaHelper = { + ....... + ccPrivateKeyFile: process.env.OKTA_CC_PRIVATE_KEY_FILE || '', // Private Key for signing Private key JWT + ccPrivateKey: null, + // Add this code ====================== + dpopPrivateKeyFile: process.env.OKTA_DPOP_PRIVATE_KEY_FILE || '', // Private key for signing DPoP proof JWT + dpopPublicKeyFile: process.env.OKTA_DPOP_PUBLIC_KEY_FILE || '', // Public key for signing DPoP proof JWT + dpopPrivateKey: null, + dpopPublicKey: null, + // Add above code ====================== + accessToken: '', + ..... +} +``` + +Add a helper method to generate a DPoP value. This helper method adds an access token to the DPoP proof JWT header. It'll construct the JWT based on the format defined in [spec](https://datatracker.ietf.org/doc/html/rfc9449#section-4.2). + +```javascript +const oktaHelper = { + ..... + // Add this as the last attribute of oktaHelper object + generateDpopToken: function(htm, htu, additionalClaims) { + let privateKey = this.dpopPrivateKey || fs.readFileSync(this.dpopPrivateKeyFile); + let publicKey = this.dpopPublicKey || fs.readFileSync(this.dpopPublicKeyFile) + let signingOptions = { + algorithm: 'RS256', + expiresIn: '5m', + header: { + typ: 'dpop+jwt', + alg: 'RS256', + jwk: JSON.parse(publicKey) + } + }; + let payload = { + ...additionalClaims, + htu, + htm, + jti: this.getNewJti() + }; + return jwt.sign(payload, privateKey, signingOptions); + } +}; +``` + +Next, add the DPoP proof token to the `tokenRequest` method. This method gets the newly generated DPoP proof token and adds it to the token request as a header. + +```javascript +// Add dpopToken as a new parameter +tokenRequest: function(ccToken, dpopToken) { // generate token request using client_credentials grant type + return fetch(this.getTokenEndpoint(), { + method: 'POST', + headers: { + Accept: 'application/json', + 'Content-Type': 'application/x-www-form-urlencoded', + // New Code - Start + DPoP: dpopToken + // New Code - End + }, + ... + }); +}, +``` + +Add the following steps to the `authenticate` method to add DPoP. + * Generate a new DPoP proof for `POST` method and *token endpoint* + * Make token call with both `private_key_jwt` and `DPoP` jwt + * Okta adds an extra security measure by adding a `nonce` to token requests requiring DPoP. This will respond to token requests that don't include a nonce with the `use_dpop_nonce` error. Read more about the nonce [in the spec](https://datatracker.ietf.org/doc/html/rfc9449#name-authorization-server-provid). + * After this step, we'll generate a new DPoP proof JWT including nonce value in payload + * Make the token call again with this new JWT + +Once we follow these steps, we'll have a new access token to use in our API call. Let's implement the steps. Update the `authenticate` method to the following: + +```javascript +authenticate: async function() { // Use to authenticate and generate access token + if(!oktaHelper.accessToken) { + console.log('Valid access token not found. Retrieving new token...\n'); + let ccToken = oktaHelper.generateCcToken(); + console.log(`Using Private Key JWT: ${ccToken}\n`); + + // New Code - Start + let dpopToken = oktaHelper.generateDpopToken('POST', oktaHelper.getTokenEndpoint()); + console.log(`Using DPoP proof: ${dpopToken}\n`); + // New Code - End + + console.log(`Making token call to ${oktaHelper.getTokenEndpoint()}`); + + // Update following line by adding dpopToken parameter + let tokenResp = await oktaHelper.tokenRequest(ccToken, dpopToken); + let respBody = await tokenResp.json(); + + // New Code - Start + if(tokenResp.status != 400 || (respBody && respBody.error != 'use_dpop_nonce')) { + console.log('Authentication Failed'); + console.log(respBody); + return null; + } + let dpopNonce = tokenResp.headers.get('dpop-nonce'); + console.log(`Token call failed with nonce error \n`); + dpopToken = oktaHelper.generateDpopToken('POST', oktaHelper.getTokenEndpoint(), {nonce: dpopNonce}); + ccToken = oktaHelper.generateCcToken(); + console.log(`Retrying token call to ${oktaHelper.getTokenEndpoint()} with DPoP nonce ${dpopNonce}`); + tokenResp = await oktaHelper.tokenRequest(ccToken, dpopToken); + respBody = await tokenResp.json(); + // New Code - End + + oktaHelper.accessToken = respBody['access_token']; + console.log(`Successfully retrieved access token: ${oktaHelper.accessToken}\n`); + } + return oktaHelper.accessToken; +} +``` + +Before proceeding, make sure to enable DPoP in your Okta service application. Now, test the steps by running `npm start` in the terminal. OOPS! You would have received an access token, but a call to the user's API failed with a 400 status. We didn't include the DPoP proof in this API call. With DPoP enabled, we must include a new DPoP proof for every call. This prevents malicious actors from reusing stolen access tokens. + +Let's add some code to include DPoP proof during every API call. + +In the `oktaService.js` file, add a helper method to generate the hash of the access token or `ath` value. You'll use this value later to bind access tokens with DPoP proofs: + +```javascript +const oktaHelper = { + ....., + // Add as the last attribute of oktaHelper object + generateAth: function(token) { + return crypto.createHash('sha256').update(token).digest('base64').replace(/\//g, '_').replace(/\+/g, '-').replace(/\=/g, ''); + } +}; +``` + +A valid DPoP proof JWT includes the access token hash (`ath`) value. To make this change, update `managementApiCall` method + +```javascript +managementApiCall: function (relativeUri, httpMethod, headers, body) { // Construct Okta management API calls + let uri = `${oktaHelper.oktaDomain}${relativeUri}`; + + // New Code - Start + let ath = oktaHelper.generateAth(oktaHelper.accessToken); + let dpopToken = oktaHelper.generateDpopToken(httpMethod, uri, {ath}); + // New Code - End + + // Update reqHeaders object + let reqHeaders = { + 'Accept': 'application/json', + 'Authorization': `DPoP ${oktaHelper.accessToken}`, + 'DPoP': dpopToken, + ...headers + }; + return fetch(uri, { + method: httpMethod, + headers: reqHeaders, + body + }); +} +``` + +Run `npm start`. Voila! You see a list of users! + +We successfully authenticated to Okta with a service app demonstrating DPoP and are using this access token and DPoP proof to access Okta Admin Management API endpoints. + +## Experiment with DPoP and API scopes for Okta API and custom resource server calls + +You can download the completed project from the [GitHub repository](https://github.com/oktadev/okta-node-dpop-example). + +Try modifying the project using different Okta API scopes and experimenting with other endpoints. Ensure you give permissions to your service app by assigning appropriate Admin roles. To improve security, you can implement similar protection to your custom resource server endpoints using a custom authorization server and custom set of scopes. + +## Learn more about Okta Management API, DPoP, and OAuth 2.0 + +In this post, you accessed Okta management API using a node app and were able to make it more secure by adding DPoP support. I hope you enjoyed it! If you want to learn more about the ways you can incorporate authentication and authorization security in your apps, you might want to check out these resources: + +* [Elevate Access Token Security by Demonstrating Proof-of-Possession](/blog/2024/09/05/dpop-oauth) +* [Okta Management API reference](https://developer.okta.com/docs/reference/) +* [OAuth 2.0 and OpenID Connect overview](https://developer.okta.com/docs/concepts/oauth-openid/) +* [Implement OAuth for Okta](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/) +* [Configure OAuth 2.0 Demonstrating Proof-of-Possession](https://developer.okta.com/docs/guides/dpop/-/main/) + +Remember to follow us on [Twitter](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/c/OktaDev/) for more exciting content. We also want to hear from you about topics you want to see and questions you may have. Leave us a comment below!