Upsert an identity provider

POST /idps
Bearer auth

Token exchange involves exchanging an identity provider-signed token for a State Backed-signed token. By adding an identity provider configuration to State Backed, you are instructing State Backed to trust any valid token from that identity provider when evaluating whether to allow a token exchange. You are also extracting the claims from that token that you want to make available to your token providers to include in the State Backed token.

For example, if you are using Auth0 as your identity provider, you can configure State Backed to trust your Auth0 tokens by calling:

curl -XPOST https://statebacked.dev/idps \
  -H 'authorization: Bearer sbsk_...'
  --data '{
    "aud": "https://<your-auth0-domain>.us.auth0.com/api/v2/",
    "iss": "https://<your-auth0-domain>.us.auth0.com/",
    "jwksUrl": "https://<your-auth0-domain>.us.auth0.com/.well-known/jwks.json",
    "algs": ["RS256"],
    "mapping": {
      "sub.$": "$.sub",
      "email.$": "$.email",
      "provider": "auth0",
    }
  }'

State Backed uses the audience (aud) and issuer (iss) claims in any tokens provided for exchange to identify the identity provider to use for verification.

In this example, token providers would be have access to sub, email, and provider claims that they could include in the resultant State Backed token.

Upserts may change algorithms, mappings, keys or jwksUrls.

This endpoint requires admin access.

Body

Identity provider configuration

  • key string

    base64url-encoded key to use to verify token signatures (one of key or jwksUrl must be provided)

  • jwksUrl string

    Absolute URL at which to find a JWKS key set to verify token signatures (one of key or jwksUrl must be provided)

  • aud string

    The audience claim that identifies tokens from this identity provider (one of aud or iss must be provided)

  • iss string

    The issuer claim that identifies tokens from this identity provider (one of aud or iss must be provided)

  • algs array[string] Required

    Allowed signing algorithms

    Values are HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512, ES256, ES384, ES512, or EdDSA.

  • mapping object Required

    A mapping object that extracts claims from the identity provider tokens that token providers can reference when creating the claims for State Backed tokens.

    The values of properties that end in ".$" are treated as JSONPath references into the claim set of the provided token.

    So a mapping of { "sub.$": "$.sub" } with identity provider claims of { "sub": "user-123" } will result in { "sub": "user-123" } as the input claims into any token provider.

    Hide mapping attribute Show mapping attribute

Responses

  • 204

    The identity provider was created or updated.

POST /idps 
curl \
 -X POST https://api.statebacked.dev/idps \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"key":"string","jwksUrl":"string","aud":"string","iss":"string","algs":["HS256"],"mapping":{}}'
Request example 
{
  "key": "string",
  "jwksUrl": "string",
  "aud": "string",
  "iss": "string",
  "algs": [
    "HS256"
  ],
  "mapping": {}
}
Request examples 
{
  "key": "string",
  "jwksUrl": "string",
  "aud": "string",
  "iss": "string",
  "algs": [
    "HS256"
  ],
  "mapping": {}
}