Skip to main content

Understand Authentication Response

Learn about user profile and session information provided to your application by AuthN

User profile and session tokens​

After a user completes authentication, AuthN responds with a JSON object containing user profile details and session tokens linked to the user's session in your Pangea project. You are likely to use the following information found under the "result" key in the response:

Opaque Session Tokens​

To use opaque active tokens in your Pangea project, select the Opaque Session Tokens option in AuthN Session Settings within the General section and click Save. With this option, the active token value will be a hashed string. For example: ptu_6kt3p36zcxnyqigbyxqwqozazbbnb4ht.

The token body doesn't bear any useful information, but is it linked to the user session and you can use it with the AuthN APIs:

JSON Web Tokens (JWT)​

You can receive a list of claims about the authenticated user in a signed JWT. In Session Settings, select the JSON Web Tokens (JWT) option and use the Configure a signing key button to create or import a pair of public and private keys, which will be saved in Vault.

Once your application decodes a JWT and verifies its signature, you are likely to use the following fields in your application:

  • "sub" - Provides the Pangea unique identifier for the user.
  • "exp" - Specifies the token expiration date expressed in seconds since the Unix epoch (January 1, 1970, UTC). You can use it as an indication of when to renew the active token.
  • "email" - Provides the user's email address.
  • "profile" - Contains a JSON with the additional user profile fields.
  • "intelligence" - Contains the intelligence report, which you can use to evaluate whether your application should proceed with the current user session.

A signed JWT could serve as an authoritative confirmation of the user authentication by Pangea without additional inquiries to AuthN APIs.

note

You can also use a non-decoded JWT value with AuthN APIs in the same way you'd use an opaque active token value.

Verify JWT signature​

To verify the signature of a JWT received by your application, your application can retrieve the public key from the JSON Web Key Set (JWKS) available at the issuer's /jwks.json path. Pangea issues standard JWTs that can be validated with JWKS using your favorite library. This approach to validate JWTs is widely supported.

In protected environments, you could also retrieve the corresponding public key using Vault APIs.

Use JWKS​

If your application, such as a mobile app, cannot safely store the Vault service token, you can instead use the publicly available JWKS to generate the public key. Append /jwks.json path to the issuer URI in a decoded JWT and use it to retrieve the JWKS. For example:

jwks.json
{
  "keys" : [
      ...,
      {
        "alg" : "ES256",
        "crv" : "P-256",
        "kid" : "pvi_dzbpej6fegceveo66ofsjc6jq4nt5xwh|2",
        "kty" : "EC",
        "x" : "HNVhj_BFpDZWc5i-1TRR2dLmSgvzlLbKD6BUDsUKGeo",
        "y" : "laA5au3cuwoy78dwzi7E2urphJpk8tUF0RBHaavdQe8"
      },
      {
        "alg" : "ES256",
        "crv" : "P-256",
        "kid" : "pvi_dzbpej6fegceveo66ofsjc6jq4nt5xwh|1",
        "kty" : "EC",
        "x" : "kWqMYYDrxFLR0S88wxisf6ro7JaQwRZlDhSUiHPe9sc",
        "y" : "MFxmc5OF4cRaQ0dDakw6pAG3xIINFeyzuYqWeQs19yk"
      }
  ]
}

New versions of keys will be added to the set as the JWT key saved in Vault is rotated. The key version is shown in the "kid" value after the | delimiter.

To automate the JWKS retrieval and application you can use one of the JWT Libraries for Token Signing/Verification .

Example:

pip install 'pyjwt[crypto]'
Use JWKS
import jwt
from jwt import PyJWKClient

token = "eyJhbGciOiJFUzI1NiIsImtpZCI6InB2aV9qZGp5amFudnZtb3hpMnB1N3RtcWFnY3B4enV2bnViZXw1Iiwia3R5IjoiSldUIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
url = "<JWKS-path>"
jwks_client = PyJWKClient(url)
signing_key = jwks_client.get_signing_key_from_jwt(token)
data = jwt.decode(
  token,
  signing_key.key,
  algorithms=["ES256"],
  options={"verify_exp": False},
)

print(data)
Use public key from Vault​

To obtain the public key dynamically, you can request it from the Vault /v1/get endpoint by providing the JWT key ID and authorizing the request with a Vault service token. You can get the default service token for Vault from its Configuration Details under Vault Overview in the Pangea User Console, or you can create a service token in Project Settings >> Tokens and explicitly associate it with Vault.

export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_VAULT_TOKEN="pts_gqmqvvxk4yhirapuhw6bs7nswu"

Note that the items in Vault can be versioned. Rotating the JWT signing key will require the use of an appropriate version of the public key in your application. In the request data, you can optionally provide the version number or request all versions of the public key via the "version" parameter. If you don't specify a version in your request, the latest will be returned.

/v1/get JWT public key
curl --location "https://vault.$PANGEA_DOMAIN/v1/get" \
--header "Authorization: Bearer $PANGEA_VAULT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id":"pvi_jdjyjanvvmoxi2pu7tmqagcpxzuvnube",
  "version":"all"
}'

The latest public key version for verifying the JWT signature will be included as result.current_version.public within the response. Older versions can be found in the "version" array. Including previous keys allows you to accept tokens minted just before the signing key has been rotated, either manually or on an automated schedule.

/v1/get response
{
  "result": {
    "current_version": {
      "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGY4p4VYSqOAh2yncQE31kJaWzgAr\n/fVvYAyf7hnkd6bhJmN24IiujCiYhKiRWA7QGwF7jmPvTDjxwd4/0RSt8Q==\n-----END PUBLIC KEY-----\n",
      "state": "active",
      "version": 1,
      ...
    },
    "id": "pvi_jdjyjanvvmoxi2pu7tmqagcpxzuvnube",
    "item_state": "enabled",
    "metadata": {
      "authn_config_id": "pro_jbxwlzvhyubldhe27fa57t234k52jda3"
    },
    "purpose": "jwt",
    "type": "asymmetric_key",
    ...
    "versions": [
      {
        "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGY4p4VYSqOAh2yncQE31kJaWzgAr\n/fVvYAyf7hnkd6bhJmN24IiujCiYhKiRWA7QGwF7jmPvTDjxwd4/0RSt8Q==\n-----END PUBLIC KEY-----\n",
        "state": "active",
        "version": 5,
        ...
      },
      ...,
      {
        "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo4Y3Vh3dU2EaiFrPAZ1LKVukdHz5\n7wKJmEOMB4x8TyvIEuC/w61yr3fdU23rBpyPguAx/IWnVI2UV8TAjZ7HVQ==\n-----END PUBLIC KEY-----\n",
        "state": "deactivated",
        "version": 1,
        ...
      }
    ]
  },
  "status": "Success",
  "summary": "Key pair retrieved",
  ...
}

In the above example, the latest/current version is 5.

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5kCKMlbs8eYSxV8JzGkpmy1CI9BO
AJHqsQ2ubRr1dQkVwH183NFs6/8khtMUTtCzmtZ7F/hjAVG7QUxkzt/kLA==
-----END PUBLIC KEY-----
note

For testing your JWT, for example on https://jwt.io/, you can get a public key from Vault Secrets & Keys in the Pangea User Console:

  1. Navigate to AuthN General >> Session Settings and click the Signing Key Vault ID link. This will take you to the JWT key saved in Vault.
  2. The JWT Key form for the selected Vault item should be opened on the right-hand side. If it is not, click on the row representing your JWT Key.
  3. In the JWT Key form, click the triple-dot menu button and select Copy public key.
  4. Save the key in a location accessible to your application.

Was this article helpful?

Contact us