OpenPass security considerations

OpenPass uses a number of security mechanisms to ensure information is safely transmitted. They include the following.

If you discover a security vulnerability, please report it using this form.

Redirect URIs

IMPORTANT: If there is a problem with the redirect URI, OpenPass does not redirect the user back to the original page. Instead, an error will be displayed in the OpenPass sign-in form.

Providing a list of redirect URIs in your account is a key security mechanism to stopping malicious actors. You set up one or more redirect URIs in your account, and then you provide one of the URLs to the API or SDK for the redirect_uri value used in API calls.

The redirect_uri value you provide must match one of the values set up in your account. Taking the user back to the webpage that the user started from, where the user clicked the Sign In with OpenPass button, must be done as an extra step after user authentication is complete on the organization's site. One popular approach is to store the originating URL in local storage or on a cookie in the browser, and then use this value to perform that extra redirect to take the user back to the original page.

For a successful redirect, the GET /v1/api/authorize request must meet the following conditions:

• The redirect_uri parameter must be present and valid. If the parameter is missing, or the value is invalid, the request fails.
• The value of the redirect_uri parameter must match one of the redirect URI values pre-registered in the organization's account settings.

PKCE

To prevent the malicious interception of information during authentication, OpenPass offers PKCE as an optional security measure.

When PKCE is used, the authorization request message includes an additional value, and the token request message includes another value that has a relationship to that. By comparing these two values, the authorization server can verify that the token request message is genuine. A malicious actor intercepting the response to the first message cannot impersonate the organization and falsely receive the ID token.

According to the PKCE standard, the token request message value can be sent in plain text, or hashed and encoded.

If you're using an OpenPass SDK, it will apply hashing and encoding.

Client credentials

To complete the process of signing in a consumer with OpenPass, the organization first requests an authorization code from the authorization server (API endpoint GET /v1/api/authorize). The organization then receives and sends the authorization code to the token endpoint to get the OpenID Connect ID token and access token (API endpoint POST /v1/api/token).

At each step of this process, it's important that communication from both parties, OpenPass and the organization, is trusted. An important way to do that is to send client credentials to OpenPass.

The credentials, established as part of the account setup, are:

• Client ID
• Client Secret

There are two options for sending client credentials:

• Basic authentication header: In this header, send the client ID and client secret. This is the preferred option if it can be sent securely. Because the Basic Authentication header includes the client secret value, it must be sent securely or not at all.
• Client ID: In the client_id parameter, send the client ID only. Do not send the client secret. Use this option if you cannot send the information securely.

IMPORTANT: If it is secure to do so, include a Basic Authentication header in the message to the token endpoint. The value of this header is the client ID and client secret, colon-separated and then Base64-encoded.
If it is not secure to send the Basic Authentication header, such as from an app, send the client ID in the client_id query parameter. Do not send the Basic Authentication header.

Basic authentication header

According to the Open ID connect specification, the request to the token endpoint should, if possible, include the HTTP Basic Authentication header, which allows the OpenPass server to authenticate the identity of the client.

The Basic Authentication header gives the OpenPass authorization server the information to complete these key security steps:

• Identify the sender (the organization).
• Verify that the message is authentic and valid.

The purpose of the message exchange is to authenticate the consumer (end-user), but trust must also be in place at each step for both OpenPass and the organization. For this reason, as long as the header can be sent securely, the client credentials are sent as the Base 64-encoded value of the Basic Authentication header.

For details, see Client Sends Code in the OpenID Connect specification.

For an example, see Authorization in the Examples section (Mozilla documentation).

Construct the basic authentication header

The value of the Basic Authentication header is constructed from the organization's credentials, as follows:

1. Create a string of the client ID, then a colon, then the client secret value:

   {CLIENT_ID}:{CLIENT_SECRET}
   

2. Base64-encode the string.

Basic authentication header: Example

For illustration purposes, let's say the client credentials are as follows:

• Client ID: 123456789
• Client secret value: TheTradeDeskPassword

If you go to www.base64encode.org, you will see that the Base64-encoded representation of these two values, with a colon separator, is the following:

Before encoding:

123456789:TheTradeDeskPassword

After Base64 encoding:

MTIzNDU2Nzg5OlRoZVRyYWRlRGVza1Bhc3N3b3Jk

In this example, the following is the format for the Basic Authentication header that is sent with the request to the token endpoint:

Authorization: Basic MTIzNDU2Nzg5OlRoZVRyYWRlRGVza1Bhc3N3b3Jk

To verify the value of the Basic Authentication header, you can decode it at www.base64decode.org. You will see that the decoded value is made up of the client ID value, a colon separator, and the client secret value:

123456789:TheTradeDeskPassword

Client ID

For client-side implementations where it is not possible to send the client secret value securely—for example, from a mobile app that could be decompiled—there is a different approach for identifying the client. Rather than sending the Basic Authentication header, send the client_id query parameter to the POST /v1/api/token endpoint. The value of this parameter is the client ID assigned to the organization's OpenPass account.

If the Basic Authentication header is not present, the client_id query parameter is required. These two options, the client ID in a query parameter, or the client-ID-plus-client-secret value sent in the Basic Authentication header, are mutually exclusive; send one or the other, but not both.

The scenario where the client sends only the client_id value, rather than client ID and client secret, is less secure than providing both values. In this case, the following security mechanisms already in place are important:

• The additional security provided by the PKCE header.
• The client's redirect URI, which must match a redirect URI pre-configured in the client's account.

Need to report a security issue?

If you discover a security vulnerability, please report it to The Trade Desk using this form. We'll resolve it promptly.