Christopher Ottman

Christopher Ottman is a Staff Product Marketing Manager, Financial Services at Okta. He leads go-to-market strategy, messaging, and growth initiatives that help financial institutions modernize their identity infrastructure, improve customer experiences, and meet evolving security and compliance demands. Before joining Okta, he held B2B product marketing roles across fintech, SaaS, and telecom—supporting both growth-stage startups and enterprise organizations.

Based in Toronto, Christopher is passionate about connecting technology to real-world outcomes and solving meaningful customer problems. Outside of work, he loves to travel and explore new cultures around the globe.

Staff Product Marketing Manager

Millennials and Gen Z are reshaping the financial services landscape. Here's how secure, seamless identity builds the trust needed to win and retain them.

Winning the Next Generation: How Identity Powers Trust in Financial Services

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Take control of your encryption keys using the BYOK security model in your Auth0 tenant.

As the cloud continues to spread and sensitive data is entrusted to service providers, customers wonder how it is protected and how they can exercise control over the security of their data. One way to allow a customer to take control of the confidentiality of their data is to use the Bring Your Own Key (BYOK) approach. In this article, you'll learn what BYOK is and how you can leverage it in Auth0.

## What Is Bring Your Own Key?

Cloud service providers secure customer secrets and data using [envelope encryption](https://en.wikipedia.org/wiki/Hybrid_cryptosystem#Envelope_encryption). This is a proven security mechanism that ensures a high level of protection of customer data using a hierarchy of encryption keys. Specifically, to encrypt data, the cloud provider platform uses Data Encryption Keys that are wrapped by a Root Key. So, to access the Data Encryption Key, a service needs access to the Root Key. Optionally, other intermediate keys can exist between the Data Encryption Keys and the Root Key.

This hierarchy not only enables data protection but also aims at protecting the encryption keys. Encryption and decryption of data are performed by a Key Management System (KMS) that leverages this key hierarchy. In addition, most cloud providers use a Hardware Security Module (HSM) to store the Environment Root Key, ensuring the strongest protection.

In the end, customers' sensitive data are encrypted using the Data Encryption Key, but due to this key hierarchy, only those who have access to the root key of this hierarchy can actually access the unencrypted data.

### Why BYOK?

Usually, the cloud service provider issues and manages the Root Key. Ultimately, the cloud service provider has control over the key hierarchy, the data encryption, and the security of the customer data. However, this is not always the situation that a customer wants. There may be several reasons why a customer doesn't want the cloud service provider to control the Root Key and then the key hierarchy:

- They may need to comply with some key provenance requirements.
- They may need to comply with some data protection requirements.
- They may need to attain control of the lifecycle of the cryptography for users' sensible data.

Think of the financial or healthcare sectors, where data confidentiality is key. In these cases, cloud service providers allow customers to issue and use their own encryption key as the Root Key for the key hierarchy, hence the name **Bring Your Own Key** (BYOK) for this approach to take control of the encryption in a cloud environment.

## BYOK in Auth0

As with any cloud service provider, Auth0 by Okta uses envelope encryption to secure customer data, too. To encrypt data, Auth0 uses Data Encryption Keys that are wrapped by a Tenant Master Key, which in turn is wrapped by the Environment Root Key. Take a look [here](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys#auth0-key-hierarchy) to have more details on the Auth0 key hierarchy.

Auth0 stores the Environment Root Key in a Hardware Security Module (HSM), which is deployed in a highly available, multiple geographic configuration. In other words, the HSM will failover to another region in case of a severe region-wide incident. The HSMs are available for [the two private cloud deployments](https://auth0.com/docs/deploy-monitor/deploy-private-cloud) supported by Auth0 &mdash; AWS and Azure &mdash; with [different encryption algorithms](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys#environment-root-key).

With BYOK, Auth0 allows tenant administrators to securely import their own Root Key to the respective cloud provider's HSM. They can use the Auth0 Dashboard or Management API to replace the Auth0 Environment Root Key with their own Customer Provided Root Key, as you will see in the next section.

> Bring Your Own Key is available on [Enterprise plans](https://auth0.com/pricing) with [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) add-on.

## How to Bring Your Key in Auth0

In this section, you will learn how to import your own encryption key in your Auth0 environment using the Auth0 dashboard. Make sure you have an Enterprise plan with the Highly Regulated Identity add-on to be able to use this feature. Basically, the process consists of three steps:

1. Generate and download a wrapping encryption key from the Auth0 dashboard.
2. Generate your own encryption key and wrap it with the downloaded wrapping encryption key.
3. Upload the wrapped encryption key via the Auth0 dashboard.

For demo purposes, you will use OpenSSL to generate and wrap your encryption key, but in a real-world scenario, you should use an HSM, either on-premises or cloud-based, for key generation.

> Make sure you have [OpenSSL](https://www.openssl.org/) installed on your machine. If you have a macOS machine, be aware that it ships with [LibreSSL](https://www.libressl.org/), which is a fork of OpenSSL and has some differences.

### Get the wrapping encryption key

The first step is to get the wrapping encryption key from Auth0. Go to your [Auth0 dashboard](https://manage.auth0.com), click the *Settings* menu item, and select the [Encryption Keys](https://manage.auth0.com/#/tenant/encryption_keys) tab. You will see the following screen:

![Encryption keys management in the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/3PBjaL5gFyc2iULvFb8ZSk/ad53ccc8484a587cdbea4ed60dec1efd/auth0-dashboard-encryption-keys.png)

Now, click the *Upload Key* button and you will get the modal shown below:

![Download Auth0 wrapping encryption key](https://images.ctfassets.net/23aumh6u8s0i/2ED5p9T6aUpnWPZkGffLcn/ac4069f77c95709a1034d6c80bc3bbef/download-wrapping-encryption-key.png)

Click the *Download* button to get the wrapping encryption key from Auth0. This ensures that your own key will be securely transferred to Auth0.

> Until you have uploaded your own key, Auth0 will continue to use the built-in Environment Root Key.

### Generate and wrap your own key

If you are using a Hardware Security Module to generate your key, follow its specific instructions. For test purposes, we are using Open SSL here, which requires some preprocessing of the content of the PEM file you downloaded from Auth0, the key generation, and then the actual key wrapping. Let's examine each step.

#### Preprocess the wrapping key

Open the file with a text editor and manually remove the PEM header and footer, i.e., the `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` strings. Then, remove all the line breaks in the file. The result will be a one-line file with the bits of the key.

Now, decode the content of this file from Base64 to binary. In Linux-based systems and macOS, you can use the [`base64`](https://www.gnu.org/software/coreutils/manual/html_node/base64-invocation.html) builtin tool as shown in the following example:

```bash
cat wrapping-key.pem | base64 -d > wrapping-key.bin
```

Assuming that your Base64-encoded file is named `wrapping-key.pem`, the previous command generates the binary decoded version into the file named `wrapping-key.bin`.

On Windows systems, you can use the [`certutil`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/certutil) tool as follows:

```powershell
certutil -decode wrapping-key.pem wrapping-key.bin
```

#### Generate your own key

Each [cloud provider has its own requirements](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard#cryptographic-material-requirements) for the key you should generate, so you should use the appropriate settings for the [CKM\_RSA\_AES\_KEY\_WRAP](https://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cos01/pkcs11-curr-v2.40-cos01.html#_Toc408226894) algorithm parameters.

Assume you are using AWS as your Auth0 cloud provider in our example. You can generate your 32 bytes (256 bits) symmetric key as follows:

```bash
openssl rand -out customer-key-material-key.bin 32
```

You also need a 32 bytes-long ephemeral AES encryption key that is required for AES Key Wrap with padding step:

```bash
openssl rand -out ephemeral-aes-kek-kwp.bin 32
```

Now you have two new files:

- `customer-key-material-key.bin`, which contains your symmetric key that will be used instead of the Auth0 Environment Root Key. Let's call it the *customer key*.
- `ephemeral-aes-kek-kwp.bin`, which contains another symmetric key that will be used to wrap the *customer key*, as [required by AWS](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard#auth0-on-aws-cloud). Let's call it the *ephemeral key*.

#### Wrap your own key

Let's start by wrapping the *customer key* with the *ephemeral key*. Use the following command:

```bash
openssl enc -id-aes256-wrap-pad \
        -K "$(xxd -p < ephemeral-aes-kek-kwp.bin | tr -d '\n')" \
        -iv A65959A6 \
        -in customer-key-material-key.bin \
        -out customer-key-material-wrapped.bin
```

You will get the `customer-key-material-wrapped.bin` file.

Now, wrap the *ephemeral key* with the wrapping key you downloaded from Auth0 and preprocessed earlier:

```bash
openssl pkeyutl \
    -encrypt \
    -in ephemeral-aes-kek-kwp.bin \
    -out ephemeral-aes-kek-kwp-wrapped.bin \
    -inkey wrapping-key.bin \
    -keyform DER \
    -pubin \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256
```

The result of this command will be the `ephemeral-aes-kek-kwp-wrapped.bin` file.

As the final step, concat the two wrapped files you generated and encode the result with Base64:

```bash
cat ephemeral-aes-kek-kwp-wrapped.bin customer-key-material-wrapped.bin | base64 > encrypted-key-material-b64
```

The file `encrypted-key-material-b64` is the file you will upload to Auth0 to complete the BYOK process.

### Upload your newly created Root Key

Go back to your Auth0 dashboard and follow the steps again to open the modal to upload the key. This time, click the *Choose File* button and select the `encrypted-key-material-b64` file you created in the previous step:

![Upload customer key to complete BYOK](https://images.ctfassets.net/23aumh6u8s0i/5MSJvTULvP0zSYga5Nzjhq/22c95f9d6faa2e2a3a7ad27c457cc647/upload-customer-key-byok.png)

Click the *Save* button to complete the BYOK process.

Congratulations! Now Auth0 will be using your own encryption key as your Environment Root Key:

![Auth0 dashboard with BYOK enabled](https://images.ctfassets.net/23aumh6u8s0i/6cKLg7wB5TYxqGRL8WRfGr/3b4a64b4d61ce3cff640f46ccddbfd5a/auth0-dashboard-with-byok-enabled.png)

> Keep in mind that by importing your own encryption key, you implicitly deauthorize Auth0 from managing the lifecycle of the Environment Root Key. This means that now you are in charge of rotating the key periodically.

## Automate the Key Generation and Wrapping

As you can see, there are a few manual steps to generate and wrap the encryption key to upload to Auth0. Fortunately, you can blend it all into one script as the following (only for Bash):

```bash
#!/bin/bash

# Check if a .pem file is passed as an argument
if [ -z "$1" ]; then
    echo "Usage: $0 <path to pem file>"
    exit 1
fi

PEM_FILE="$1"

#Ensure the file exists
if [ ! -f "$PEM_FILE" ]; then
    echo "File not found: $PEM_FILE"
    exit 1
fi

#1. Remove the first line (BEGIN CERTIFICATE)
#1. Remove the last line (END CERTIFICATE)
#1. Remove  all line breaks
#4. Remove any trailing characters like whitespace

CERT_DATA=$(sed '1d;$d' "$PEM_FILE" | tr -d '\n\r' | tr -d ' ')


if [ -z "$CERT_DATA" ]; then
    echo "Cleaned certificate is empty"
    exit 1
fi


echo "Processed certificate data: $CERT_DATA"

PUBLIC_WRAPPING_KEY=public-wrapping-key.bin

printf "%s" "$CERT_DATA" | base64 -D  > $PUBLIC_WRAPPING_KEY

if [ ! -f "$PUBLIC_WRAPPING_KEY" ]; then
    echo "Public Wrapping key file does not exist"
    exit 1
fi

openssl_operations() {
    echo "Running OpenSSL..."

    openssl rand -out customer-key-material-key.bin 32
    openssl rand -out ephemeral-aes-kek-kwp.bin 32
    openssl enc -id-aes256-wrap-pad \
        -K "$(xxd -p < ephemeral-aes-kek-kwp.bin | tr -d '\n')" \
        -iv A65959A6 \
        -in customer-key-material-key.bin \
        -out customer-key-material-wrapped.bin

    openssl pkeyutl \
    -encrypt \
    -in ephemeral-aes-kek-kwp.bin \
    -out ephemeral-aes-kek-kwp-wrapped.bin \
    -inkey public-wrapping-key.bin \
    -keyform DER \
    -pubin \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256

    cat ephemeral-aes-kek-kwp-wrapped.bin customer-key-material-wrapped.bin | base64 > encrypted-key-material-b64 

    rm customer-key-material-key.bin ephemeral-aes-kek-kwp.bin customer-key-material-wrapped.bin ephemeral-aes-kek-kwp-wrapped.bin public-wrapping-key.bin

    # echo "$DECODED_CERT" | openssl ...
}

openssl_operations
```

This simplifies the generation and wrapping steps, making the process more straightforward, as you can see in the following video:

<AmpContent>
<amp-youtube
    data-videoid="InbHi6fRMKo"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  className='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/InbHi6fRMKo'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

This article showed you how Auth0 supports Bring Your Own Key, an approach that lets you control the provenance of the root key used to encrypt your secrets and data in the Auth0 environment.

You used OpenSSL as a testing tool to generate and wrap your own key and learned how to use the Auth0 dashboard to configure your environment with it.

A special thanks to Filip Palach and Lucas Gomes for their work on the OpenSSL process and the script.

If you want to learn more about BYOK in Auth0, leave a message below.


Bring Your Own Key (BYOK) in Auth0

Learn what Pushed Authorization Requests are and when to use them to strengthen the security of your OAuth 2.0 and OpenID Connect-based applications.

In highly sensitive contexts, such as in financial or healthcare sectors, the security bar must be raised to prevent any breach of information and artifacts that could give unauthorized access to user data. [Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/html/rfc9126) is one extension that enhances OAuth 2.0  and OpenID Connect so that they can be securely used in these scenarios. Let's explore how this OAuth 2.0 extension works.

## Why use PAR?

Let's start by first understanding why you may need PAR and what problem it tries to resolve.

### The OAuth authorization request

If you have some experience with OAuth 2.0 and OpenID Connect, you know that the initial step that a client application must take to get the tokens it needs is to send an authorization request to the authorization server. For this purpose, the user's browser is redirected to the authorization server with a URL similar to the following:

```bash
https://your-authorization-server.com/authorize?
    client_id=1234567890&
    redirect_uri=https://your-app/callback&
    scope=openid profile email phone address&
    response_type=code&
    audience=https://myapi&
    state=12c1d32c1aba2cc14f9b907a9ec90
```

This authorization request URL is pretty basic, but you can add other parameters based on the [OAuth flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow) you are using or on the specific extension/customization your authorization server implements. For example, if you are using the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), you should also add the `code_challenge` and `code_challenge_method` parameters. In Auth0, you can also specify the `organization` or `invitation` parameters if you are using the [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations) feature, and so on. The complexity of the authorization request can grow considerably depending on your specific use case.

### What's the problem with the authorization request?

As you can see, the authorization request is nothing but a GET HTTP request against a URL with its parameters:

```http
GET /authorize?
    client_id=1234567890&
    redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
    scope=openid%20profile%20email%20phone%20address&
    response_type=code&
    audience=https%3A%2F%2Fmyapi&
    state=12c1d32c1aba2cc14f9b907a9ec90 HTTP/1.1
Host: your-authorization-server.com
```

In this form, it may raise a few concerns:

- **The authorization request can be altered**. Usually, the client application redirects the user's browser to the authorization server with the authorization URL. Nothing prevents a malicious actor from changing one or more parameters of this request before sending it to the authorization server.
- **No guarantee of the request's provenance**. The authorization request is normally built by the client application, and the user's browser is in charge of sending it to the authorization server. However, there is no guarantee that the request has been built by the client application. Anyone can build an authorization request once they know a few data, such as the client ID and the redirect URI.
- **No guarantee of confidentiality**. Although the browser sends the authorization request via HTTPS, the request parameters can be intercepted by third-party applications, such as a proxy, a load balancer, or even a browser plugin. A malicious network component of this type can inject or change the request parameters, not to mention that the request itself can be logged.
- **Browser limitations**. Finally, a very complex query string in the authorization request may incur [possible browser limitations on URL length](https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers).

This is where Pushed Authorization Requests come into play.

## How PAR Works

The basic idea of Pushed Authorization Requests is very simple: instead of redirecting the user's browser to make the authorization request with all the parameters, the client application *pushes* that request directly to the authorization server with a POST request and gets an identifier for that request. Now, the client application redirects the user's browser to the authorization server with just that identifier to make its authorization request, avoiding exposing all the details.

### The PAR endpoint

The first requirement for an authorization server supporting PAR is to expose the PAR endpoint. This is an additional endpoint that will accept authorization requests with the parameters in the payload. The following example shows how a request to the PAR endpoint looks like:

```http
POST /oauth/par HTTP/1.1
  Host: your-authorization-server.com
  Content-Type: application/x-www-form-urlencoded
  client_id=1234567890&
  client_secret=<YOUR_SECRET>&
  redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
  scope=openid%20profile%20email%20phone%20address&
  response_type=code&
  audience=https%3A%2F%2Fmyapi
```

Notice the reference to the `/oauth/par` path and how the parameters are passed through POST. You can see some differences between the parameters passed in the standard GET-based authorization request and this request. Apart from the usual parameters such as `client_id`, `redirect_uri`, `scope`, etc., you may notice that the `client_secret` is passed here. This is a request coming from a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications), that is, a client capable of securely storing a secret, such as a server-running application. By passing `client_id` and `client_secret`, the request is authenticated by the authorization server resolving the confidentiality concerns we discussed earlier.

> The PAR specification does not limit access to the PAR endpoint to confidential clients only. It states that "*the rules for client authentication as defined in [[RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)] for token endpoint requests, including the applicable authentication methods, apply for the PAR endpoint as well.*"
>
> This entails that even public clients can potentially access the PAR endpoint. However, their public nature does not allow them to safely determine their identity, so some of the concerns about the integrity and confidentiality of the request still remain in this case.

As a response to this request, the authorization server will respond with something like the following:

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACi5bwq064ltcg4eY28s",
  "expires_in": 30
}
```

The authorization server's response is a JSON object with two properties:

- `request_uri`. This is the identifier of the authorization request pushed by the client application.
- `expires_in`. This is the number of seconds that the authorization request is valid.

With these basic notions, let's take a look at how the whole authorization process works.

### The PAR authorization flow

The following diagram illustrates the OAuth authorization flow using PAR:

![Pushed Authorization Request flow](https://images.ctfassets.net/23aumh6u8s0i/6FWUrUsNmimPr10XuqI26k/984cf829065bab1dacd1a6dafc08e92c/pushed-authorization-requests-flow.png)

Here are the steps highlighted in the diagram:

1. The client application sends an authorization request to the PAR endpoint of the authorization server.

2. The authorization server authenticates the application client, validates the request, and stores it. Then, it replies with a response containing the authorization request's identifier (`request_uri`) and the validity time (`expires_in`).

3. The client application uses the `request_uri` to build the authorization request URL for the user's browser and redirects it to the authorization server. The authorization request URL will look like the following:

   ```bash
   https://your-authorization-server.com/authorize?
       client_id=1234567890&
       request_uri=urn%3Aietf%3Aparams%3Aoauth...4ltcg4eY28s
   ```

4. The user's browser sends a GET request to the authorization server using the authorization request URL received by the client application. The authorization server retrieves the authorization request identified by the `request_uri` value, and from now on, the usual steps of the requested OAuth flow are carried out.

As you can see, the browser's request no longer contains the details of the authorization request. There is no risk of tracking or in-transit manipulation of the request. Also, the complexity of the URL is considerably reduced.

<include src="ebook-ads/FapiGuide" />

## PAR Metadata

OAuth and OpenID Connect servers publish the configuration metadata in the `/.well-known` URI to publicly declare the supported capability and other protocol details. PAR specification adds two new keys to this metadata:

- `pushed_authorization_request_endpoint`. This key defines the PAR endpoint where the client application can push the authorization request and get the corresponding  `request_uri`.
- `require_pushed_authorization_requests`. This key has a boolean value indicating whether using PAR is mandatory (`true`) or optional (`false`). If this key is not present, the default value is `false`.

With this metadata, your application can check if an authorization server supports PAR using the usual [discovery approach](https://auth0.com/docs/get-started/applications/configure-applications-with-oidc-discovery).

## PAR and Auth0

Auth0 supports PAR as part of the [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) add-on of the Enterprise plan. Highly Regulated Identity is Auth0's implementation of FAPI 1, the set of standards that raises the security level to protect application operations in sensitive contexts, such as finance, healthcare, e-commerce, etc.

By default, PAR is not active in an Auth0 tenant. You have to enable it at the tenant level to make the PAR endpoint available to your applications. You can do it through your Auth0 dashboard. Follow [the steps described here to enable PAR](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-a-tenant) in your Auth0 tenant.

Once you enable PAR at the tenant level, your applications can use the classic authorization endpoint or the PAR endpoint. If you want to make the endpoint mandatory for a specific application, you should require it at the Auth0 application configuration level. You can use the Auth0 dashboard or the Auth0 Management API to set PAR endpoint mandatory. Follow [these instructions](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-an-application) to enable mandatory PAR for your application.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

Pushed Authorization Requests (PAR) are a great addition to strengthen the security of OAuth 2.0 and OpenID Connect protocols. As you have learned, it enables client applications to make authorization requests without exposing the details of the call to potential tracking and manipulation.

This security improvement is critical in scenarios where data confidentiality must be preserved, and Auth0 offers PAR support through Highly Regulated Identity (HRI). Combined with other strong security enhancements supported by HRI, you can build applications with high-security standards and comply with the most common regulations. Check out this document to learn more about [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity).



What Are OAuth Pushed Authorization Requests (PAR)?

Add Private Key JWT authentication to your .NET application to empower security in sensitive contexts.

Sensitive operations require increased security mechanisms, but at the same time, threat actors are on the rise, so it's crucial to raise the bar on application authentication security, such as using Private Key JWT authentication. Private Key JWT is a secure authentication method for applications to get security tokens from an authorization server. In this article, you will learn when you may need it, how it works, and how to implement it in a .NET application using Auth0.

## When a Client Secret Is Not Enough

In the OAuth 2.0 context, your application needs to authenticate in order to get an ID, access, and refresh token. This means that your application must provide its [credentials](https://auth0.com/docs/secure/application-credentials), typically a client ID and a secret, to the authorization server, such as Auth0.

Sensitive applications typically run in a server environment and are [confidential clients](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications), i.e., applications capable of securely storing their credentials. Typically, these are server-rendered web applications or back-end services and applications that run in a protected environment. [Public clients](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#public-applications), such as Single-Page Applications or mobile apps, can't securely store a secret. They must use [specific flows](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#grant-types) that don't include client authentication, and their level of security is generally less reliable than that of a confidential client.

Although client authentication based on client secret provides a higher level of security for obtaining the access token than a public client flow, there are contexts in which it is considered insufficient. Think of banking or financial contexts, where the highest levels of transaction security must be ensured. Or in the healthcare context, where data confidentiality must be protected.

In these contexts, various regulations (e.g., [Open Banking](https://www.openbanking.org.uk/)) require the use of more secure mechanisms to protect transactions. Among these mechanisms, they require a more secure alternative to client authentication based on client ID and secret.

## Private Key JWT Authentication

[Private Key JWT authentication](https://auth0.com/docs/secure/application-credentials#private-key-jwt-authentication) is a secure alternative to client authentication based on a secret. It's a [standard mechanism](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bearer) that relies on asymmetric cryptography to authenticate your application.

Basically, you generate a private and public key pair. Keep your private key securely stored and accessible to only your application. Don't even share it with Auth0. Share the corresponding public key with Auth0 instead. By nature, the public key is not sensitive data, so even if an attacker manages to catch it, they can't impersonate your application.

When your application needs an access token, it generates a specific JWT, called *assertion*, and signs it with its private key. Then, it sends this assertion to Auth0 in order to authenticate. The following is an example of an HTTP request to authenticate via an assertion:

```bash
curl --request POST \
  --url 'https://<YOUR-AUTH0-DOMAIN>/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<YOUR_CLIENT_ID> \
  --data client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi... \
  --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data audience=<YOUR_API_IDENTIFIER>
```

Auth0 validates the assertion using your application's public key and, if everything is ok, issues your access token.

If you want to learn more details about [how to authenticate with Private Key JWT, read the documentation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt). If you use one of the Auth0's SDKs, you don't need to build an assertion yourself, as you will see later in this article.

> Private Key JWT authentication is only available with the [Enterprise plan](https://auth0.com/pricing).



## Highly Regulated Identity and Private Key JWT Authentication

As mentioned, Private Key JWT authentication is a secure client authentication method required in business contexts where higher levels of security must be guaranteed, such as in finance, insurance, and healthcare.

To meet customers' needs in this area, Okta has released [Highly Regulated Identity (HRI)](https://auth0.com/docs/secure/highly-regulated-identity), a set of Auth0 features that enable high levels of security standards, such as [Financial Data Exchange](https://financialdataexchange.org/) and [Open Banking](https://www.openbanking.org.uk/), and compliance with widely adopted regulations, such as the [Payment Services Directive (PSD2)](https://www.europeanpaymentscouncil.eu/sites/default/files/infographic/2018-04/EPC%20Infographic_PSD2_April%202018.pdf).

> Highly Regulated Identity is an add-on for the Enterprise plan. For an overview of [Highly Regulated Identity, check out this article](https://auth0.com/blog/elevate-security-and-ux-with-highly-regulated-identity/).

Private Key JWT authentication is available in the Enterprise plan, so you don't need HRI to use it in your applications. However, if you need to use PS256 as the signing algorithm for your assertions, you need HRI on top of your Enterprise plan. HRI also supports [mutual TLS](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) as another secure mechanism for client authentication using a public-private key pair.

<include src="ebook-ads/FapiGuide" />

## The Sample Project

To see how to use Private Key JWT authentication in practice, you will use an ASP.NET Core web application that gets users' health data from a protected API. You can download the sample project by running the following command in a window terminal:

```bash
git clone -b starting-point --single-branch https://github.com/auth0-blog/dotnet-private-key-jwt-authentication
```

You will get two .NET projects:

- *HealthCkeckApi*, an ASP.NET Core Web API project that provides the user's health data through a protected endpoint.
- *HealthCheckWebApp*, an ASP.NET Core MVC application that implements the frontend used by the user to get their own health data.

You need an Auth0 account to configure and run the application. If you don't have one, you can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for free now</a>. Follow the README document to configure and run the application.

Once your application is up and running and you have logged in, you will see a page like the following:

![HealthCheckWebApp home page](https://images.ctfassets.net/23aumh6u8s0i/6sAQuTcGWazJolzmaTzicI/08d8248e7dcec5cd978f11b633512823/healthcheckwebapp-home.png)

By clicking the *Show Health Checks* button, you will see a list of data like the following:

![HealthCheckWebApp checks data](https://images.ctfassets.net/23aumh6u8s0i/3hLebkfhp5Sn552D5tuppl/f2532b77a0f0577bda3d9cc04b3ddf45/healthcheckwebapp-data.png)

You will work on the *HealthCheckWebApp* application, which represents the OAuth confidential client that needs an access token to call the protected API. The current application implementation uses the [Auth0 ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication) to authenticate the user and get the access token from Auth0 by using its client ID and secret.

You will modify this application to use Private Key JWT authentication instead of client ID and secret.

## Create and Register Your Public Key

Let's start by creating a private and public key pair. Go to the `HealthCheckWebApp` folder and generate your private and public key pair. For example, using [OpenSSL](https://www.openssl.org/) you can create the key pair with the following command:

```bash
openssl genrsa -out app_keys.pem 2048
```

This command generates an `app_keys.pem` file containing the private and public key pair you will use as a credential for your application.

Extract the public key from that file with the following command:

```bash
openssl rsa -in app_keys.pem -outform PEM -pubout -out pub_key.pem
```

You will get a `pub_key.pem` file containing only the public key. You will be sharing the public key with Auth0, while your private key must be kept safe and never shared with anyone.

Go to your [Auth0 dashboard](https://manage.auth0.com/) and open the *Credentials* tab of your application configuration page, as shown in the following image:

![Private Key JWT credentials in the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/3jt9HLrTXYTOIwYFkPWSVE/d0c86d8b49331d22f461ea5482a78fac/auth0-private-key-jwt-credentials.png)

Select *Private Key JWT*, and a window like the following will show:

![Private Key JWT credential configuration](https://images.ctfassets.net/23aumh6u8s0i/5YiXuI8YceCxplwKghjmd2/0f8e8d8440e27795de4e6666a6f4ece9/auth0-private-key-jwt-configuration.png)

This window allows you to define a Private Key JWT credential for your application. Assign a name for the credential and upload the `pub_key.pem` file containing the public key. Optionally, select the signing algorithm and set an expiration date. Finally, click the *Add Credential* button to save your changes.

You will see your credential appearing below the *Application Authentication* section:

![Auth0 Private Key JWT authentication credential list](https://images.ctfassets.net/23aumh6u8s0i/0yhreNj2u7io7iTPnyRMB/844280997c40fc67565a27eb0b4fb3bb/auth0-private-key-jwt-authentication-credentials-list.png)

> You can add multiple credentials for your application, as you will learn in a moment.

## Get Your Access Token

Your application is now configured to use Private Key JWT authentication on the Auth0 side. Let's adjust the application code to use this authentication method instead of the client ID and secret.

Open the `appsettings.json` file in the `HealthCheckWebApp` folder and remove the `ClientSecret` key. You don't need it anymore. The file's content will be as follows:

```json
// HealthCheckWebApp/appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "<YOUR-AUTH0-DOMAIN>",
    "ClientId": "<YOUR-CLIENT-ID>",
    "Audience": "https://myapi.com"
  },
  "HealthCheckApiBaseUrl": "https://localhost:7102"
}
```

Now, edit the `Program.cs` file in the `HealthCheckWebApp` folder by applying the changes highlighted in the following code snippet:

```csharp
// HealthCheckWebApp/Program.cs

// ...existing code...

// 👇 new code
var cryptoProvider = new RSACryptoServiceProvider();
cryptoProvider.ImportFromPem(File.ReadAllText("app_keys.pem"));
var securityKey = new RsaSecurityKey(cryptoProvider);
// 👆 new code

builder.Services
    .AddAuth0WebAppAuthentication(options => {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      // 👇 old code
      //options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
      options.ClientAssertionSecurityKey = securityKey;
      // 👆 new code
      options.Scope = "openid profile email";
    })
    .WithAccessToken(options =>
      {
          options.Audience = builder.Configuration["Auth0:Audience"];
      });

// ...existing code...
```

You load the key pair from the `app_keys.pem` file, generate an instance of the `RsaSecurityKey` class from the content of that file, and assign it to the `securityKey` variable. Then, you replace the assignment of the `ClientSecret` option with the `ClientAssertionSecurityKey` option and assign the value of the `securityKey` variable.

You are done! The Auth0 ASP.NET Core Authentication SDK will take care of creating the assertion and authenticate your application with Auth0 to get the access token. You will notice no difference in the behavior of the application, but under the hood your application uses a more secure authentication method to get the access token to call the protected API.

<include src="ebook-ads/dotnetIdentity" />

## Credential Rotation

When you configured your application to use Private Key JWT authentication, you should have noticed two things:

- You can set an expiration date.
- You can create multiple credentials for the application.

These two optional features allow you to further strengthen the security of Private Key JWT authentication.
In fact, setting an expiration date for a credential is always a good practice, even with secure mechanisms such as Private Key JWT.

However, setting an expiration date can cause some downtime when the old credential expires and the new one has not yet been activated. To avoid this downtime, you can add a new credential before the old one expires. This way, on the application side, you can replace the old credential with the new one before it expires, preventing the application from becoming inoperable.

For more information about credential rotation, see [the documentation](https://auth0.com/docs/get-started/applications/rotate-credentials).

## Summary

Throughout this article, you learned about Private Key JWT authentication and how it increases your application's level of security in obtaining tokens.

Together with other advanced features of Highly Regulated Identity, Private Key JWT helps achieve a high level of security and compliance required in areas such as finance, insurance, and health care.

You also saw how to implement Private Key JWT in a .NET application using the Auth0 SDK, which relieves you of the task of dealing with low-level details.

The final version of the example application code implementing Private Key JWT is available on [GitHub](https://github.com/auth0-blog/dotnet-private-key-jwt-authentication).



Use Private Key JWTs to Authenticate Your .NET Application

milan-khan

Milan is the Product Manager for advanced identity security features for customers operating in highly regulated industries. Milan is especially keen on solving consumer identity problems balancing user experience, security and compliance.

Senior Product Manager

Milan Khan

An introduction to Strong Customer Authentication (SCA), a mechanism for providing a higher level of security in sensitive contexts.

Strong Customer Authentication (or SCA for short) is a versatile authorization mechanism that first made waves in the financial services industry for digital payments, and adoption is picking up pace, even for non-financial transactions.

SCA was enacted in 2019 as a requirement of the [revised European Union (EU) Payment Services Directive (PSD2)](https://www.ecb.europa.eu/press/intro/mip-online/2018/html/1803_revisedpsd.en.html). Its main purpose is to raise security standards and reduce fraud for online and contactless payments, and it's now a part of life for millions of consumers in the EU.

PSD2 and its regulatory technical standards (RTS), along with inputs from the European Banking Authority in the form of opinions, questions, and answers, describe how SCA should be implemented by financial services organizations in EU member states. In summary and in relation to user security and authentication, this means:

- The payer needs to authenticate themselves with multi-factor authentication in order to authorize the payment.
- Multi-factor authentication (MFA) must comprise two (or more) of the following elements: knowledge, possession, and inherence.
- The payer (the consumer) gives informed consent to the payment amount and the payee's account.
- The payment transaction must be (cryptographically) linked to an amount and a payee specified by the payer (known as Dynamic Linking – this is what makes SCA different from typical “step-up MFA”).

In this blog post, we'll explore these SCA components and show how you can implement them using Auth0 by Okta! 

## Exemptions from Applying SCA

Strong Customer Authentication takes a risk-based approach, and there is a provision for exemptions to be applied to SCA. Low-risk scenarios that allow service providers not to apply SCA include:

- Payments to existing payees that have been previously authorized using SCA.
- Payments from one account to another account, where both accounts belong to the same account holder and are with the same service provider.
- The service provider has judged the payment transaction to be low risk through real-time risk and fraud analysis. The level of historic fraud will determine the threshold for amounts that can be exempted from SCA; i.e., lower levels of fraud will mean higher payment amounts can be exempt from SCA.
- Payments transactions below EUR 30 (or local equivalent) are considered "low value" and may be exempt from SCA. Service providers will have to request the payer to perform an SCA if the exemption has been used five times since the payer's last successful SCA or if the sum total of previously exempted payments exceeds EUR 100 (or local equivalent).

## Multi-Factor Authentication &mdash; Something You Know, Have, or Are

As discussed earlier, SCA mandates the use of at least two distinct authentication factors out of the three categories: knowledge, possession, and inherence.

- The **knowledge factor** is something the user knows, such as a password, a personal identification number (PIN), or an answer to a security question.
- The **possession factor** is something the user has, such as a telephone SIM card, a mobile device, or a smart card. Each of these typically has a cryptographic key, so the possession factor is essentially possession of a cryptographic key, preferably the private key of an asymmetric key pair.
- The **inherence factor** is something you are and is typically biometric verification where a user's captured biometric is compared to a reference template. This can be, for example, a fingerprint, facial, or voice biometric.

## Consent

Authorizing payments and any other sensitive transaction requires that the user know what they are authorizing and consenting to. SCA requires the user to view the payee and the payment amount before any authorization.

This concept of providing informed consent can also apply outside of payment scenarios for any sensitive transactions such as:

- Changing login and/or security settings
- Changing user profile settings, e.g., home address
- Sharing personal data

![Strong Customer Authentication user consent](https://images.ctfassets.net/23aumh6u8s0i/6kC16xojBEnAQLynhGuUM/bfb4bbeb85b87c2ab28e00faaff2a1a0/strong-customer-authentication-user-consent.jpg)

## Dynamic Linking &mdash; What Makes SCA Different

Dynamic Linking is what sets SCA apart from a regular step-up authentication prompt. Linking transaction details to the approval prompt allows users to double-check accuracy and avoid transaction tampering before approving the transaction.

When a payer (the consumer) initiates a payment, the transaction itself must be linked to the amount and payee specified by the payer. This dynamic linking generates an “authentication code,” which is unique and specific to the transaction (payee and amount). 

The authentication code is transferred through the payment and authorization processes. Any changes to the payment data (amount, payee) will invalidate the authentication code and, thus, the transaction.

> If you want to learn more about the details of SCA, here are some related documents:
>
>- Revised EU Payment Services Directive “PSD2”: [2015/2366 - EN - Payment Services Directive >- EUR-Lex](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32015L2366) 
>- SCA Publication: [Strong customer authentication requirement of PSD2 comes into force - European Commission](https://finance.ec.europa.eu/publications/strong-customer-authentication-requirement-psd2-comes-force_en)
>- Regulatory Technical Standard for SCA: [Delegated regulation - 2018/389 - EN - EUR-Lex](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32018R0389) 
>- Amendment on the RTS for SCA: [Final Report on the amendment of the RTS on SCA & CSC](https://www.eba.europa.eu/sites/default/files/document_library/Publications/Draft%20Technical%20Standards/2022/EBA-RTS-2022-03%20RTS%20on%20SCA&CSC/1029858/Final%20Report%20on%20the%20amendment%20of%20the%20RTS%20on%20SCA&CSC.pdf) 
>- Opinion of the European Banking Authority on SCA: [Opinion of the European Banking Authority on the implementation of the RTS on SCA and CSC](https://www.eba.europa.eu/sites/default/files/documents/10180/2137845/0f525dc7-0f97-4be7-9ad7-800723365b8e/Opinion%20on%20the%20implementation%20of%20the%20RTS%20on%20SCA%20and%20CSC%20%28EBA-2018-Op-04%29.pdf) 

## Strong Customer Authentication with Auth0 by Okta

[Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) (HRI) is a solution suite on the Customer Identity Cloud powered by Auth0 that delivers Financial Grade Identity™ that helps organizations elevate security, privacy, and user experience beyond login. HRI enables developers to meet the high levels of security required by companies operating within highly regulated industries like banking, insurance, and health care. You can also use HRI for other sensitive operations that require enhanced security, such as users updating their account information, admin or security settings, accessing sensitive data or apps, and more.

Here, we look at how Highly Regulated Identity can be used to build a Strong Customer Authentication solution.

### Solution architecture

The diagram below describes a possible architecture and interactions for a Strong Customer Authentication solution built on Auth0 by Okta using HRI features.

![Strong Customer Authentication flow in Auth0 by Okta](https://images.ctfassets.net/23aumh6u8s0i/31xqfrkhJVa87fbeplvGpz/459e46a7bcb42fd79aafbf1576eebdb6/strong-customer-authentication-flow-in-auth0-by-okta.png)

Important points to note:

- The blue  components are Okta-owned and part of Auth0 and Highly Regulated Identity solution suite.
- The green  components are built and maintained by the customer, e.g., customer mobile apps, applications, and services. 

### Sequence of operations

1. The user has initiated a payment transaction via their web browser at a digital banking web application, e.g., they may be making a payment from their bank account.

2. The digital banking web application sends the transaction request to Auth0:

   a. The transaction request may contain the “authentication code” for the amount and payee as part of the transaction. 

   b. The request is sent to the `/par` endpoint and avoids exposing sensitive transaction details at the browser.

3. Auth0 validates the request and generates: 

   a. A `linking_id` when the Consent Policy is configured as “Transactional Authorization with MFA” and the API audience is configured with this Consent Policy.

   b. A `request_uri` as a reference to the next step in the authorization process.

4. Auth0 sends the request_uri back to the calling web application .

5. The web application redirects the browser with the `redirect_uri`, which opens the login page in Auth0:

   a. The user can perform the login with their knowledge-based factor (i.e. their password). 

   b. This login step can be avoided if there is already a single sign-on session. 

   c. The user will wait here on this “holding page” until the decoupled flow completes.

6. Meanwhile, a [post-login trigger](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow#login-post-login) can run custom an Action code that extracts the authorization details (e.g., amount, payee, authentication code) from the transaction request.

   a. At this point, the Action code can integrate with third-party risk and fraud engines to determine whether a step-up authentication (i.e., SCA) is needed.

7. The Action writes the `linking_id` and contextual authorization details into a message store, i.e., a data store, for future retrieval.

8. Auth0 performs a lookup for the MFA mechanism to use; here, we will use a mobile push notification to a custom mobile app which embeds the Okta [Guardian SDK](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian):

   a. Auth0 sends a mobile push notification to the mobile app, along with the `linking_id`.

   b. No transaction details are sent over the push notification.

9. The customer mobile app receives the push notification with the transaction `linking_id` and calls the message store to retrieve the transaction details for the user to authorize and consent to.

10. The customer mobile app extracts the authorization details for the requested transaction, i.e., payment amount and payee, and displays this to the user for consent.

    a. The user reviews the transaction details and proceeds to accept or decline.

11. The customer mobile app with embedded Guardian SDK calls the Okta MFA endpoint with the result of the user authorization:

    a. Was the MFA action completed successfully or not?

    b. If the MFA was completed successfully, did the user accept or decline?

12. Once the mobile push-based MFA completes, the web browser is redirected from Auth0 and the MFA page back to the digital banking web application:

    a. The digital banking web application receives an authorization code.

13. The digital banking web application exchanges the authorization code for an access token:

    a. The access token contains the details from the original transaction request, including the payment amount and payee and “authentication code”.

14. The digital banking application uses the access token to consume APIs in order to initiate the payment transaction in the appropriate back-end systems.

15. The user is informed of the outcome of the payment transaction.

### Supported authentication mechanisms

The solution architecture describes SCA using a mobile push notification to a customer's mobile app with embedded Guardian SDK. However, there are alternative options that are also compliant with SCA:

- Authentication by one-time passcode (OTP) sent via SMS.
- Authentication by WebAuthn.

For both of these authentication options, the user performs the authentication on the login page and then is shown the transaction details to authorize and consent to.

## Final Words

The Highly Regulated Identity solution suite on Auth0 delivers Strong Customer Authentication for financial services and payments. The SCA solution also applies to non-payment use cases and can be applied to any sensitive operation where step-up authentication, user authorization, and consent are required.

You can read more about [Highly Regulated Identity on the Auth0 by Okta documentation](https://auth0.com/docs/secure/highly-regulated-identity).


"highly-regulated-identity"