Skip to main content
Loading...

API docs by

Create OIDC Provider

Request

Allows a user to register a new OIDC provider for a root project. The OIDC provider is registered in the project which owns the access policy being used. The idpPrefix is used to create a unique idpId for this usage of the OIDC provider within the root project. The idpPrefix cannot be the same as any existing, suspended or non-suspended, OIDC provider records for this root project. This operation creates a trust relationship between the root project and the OIDC provider such that identity tokens from the OIDC provider will be accepted for token exchange. Access control is fine-grained, based on the project in which an OIDC provider is being created.

The auth token's access policy must allow action:use/createOidcProvider.

Security
bearerAuth
Path
projectIdstring(ProjectId)^project:[0-9a-zA-Z](?![^:]*-$)(?![^:]*--)[0-...required

Globally unique identifier of a project. Callers may URL encode this value.

Example:project:abc-123
Bodyapplication/jsonrequired
namestring, [ 2 .. 100 ] charactersrequired

A human-friendly name for the identity provider.

Example:"My OIDC Provider"
trustedClientIdsArray of strings, [ 0 .. 10 ] itemsrequired

List of OAuth 2.0 client ids for this provider that are permitted to exchange ID tokens for access tokens. The value of the aud claim in an ID token is checked against this list during token exchange.

groupMembershipClaimstring, [ 2 .. 100 ] characters

Name of the claim in the ID tokens provided by this OIDC issuer whose value the STS should interpret as containing a user's group memberships, for authorization purposes. The value of the group membership claim in an ID token must be an array of strings, where each string is a unique, non-reassignable identifier for a group. When this property is not set, the STS does not interpret any claim from this provider as a group membership claim.

Example:"groups"
issuerLocationstring, [ 1 .. 2048 ] charactersrequired

The OIDC issuer location URL.

Example:"https://example.com/oidc"
idpPrefixstring^[a-zA-Z](?![^:]*-$)(?![^:]*--)[a-zA-Z0-9-]{0...required
Example:"my-idp"
Payload
{
  "name": "My OIDC Provider",
  "trustedClientIds": [
    "my-oauth-client-id"
  ],
  "groupMembershipClaim": "groups",
  "issuerLocation": "https://example.com/oidc",
  "idpPrefix": "my-idp"
}

Responses

Success

Bodyapplication/json
jwksobjectrequired

TEMPORARY: In the future, the STS will retrieve the provider's JWKS via standard OIDC Discovery mechanisms, and this will not be an input parameter!.

idpIdstring(IdentityProviderId)^idp:[a-zA-Z](?![^:]*-$)(?![^:]*--)[a-zA-Z0-9...required

Uniquely identifies a trusted Identity Provider within a root project.

Example:"idp:my-idp"
updatedAtstring(UpdatedAt)^.*$

A string timestamp indicating when the resource was last updated. Formatted like: "2025-02-12T17:24:19.033772087Z"

Example:"2024-01-15T12:00:00Z"
createdBystring(CreatedBy)^.*$required

A string indicating the principal who invoked an operation to create the resource.

Example:"principal:ABCD-EFG-12345:idp:example-user"
issuerLocationstring, [ 1 .. 2048 ] charactersrequired

The OIDC issuer location URL.

Example:"https://example.com/oidc"
namestring, [ 2 .. 100 ] charactersrequired

A human-friendly name for the identity provider.

Example:"My OIDC Provider"
createdAtstring(CreatedAt)^.*$required

A string timestamp indicating when the resource was created. Formatted like: "2025-02-12T17:24:19.033772087Z"

Example:"2024-01-15T12:00:00Z"
issuerUristring(IssuerUri)^https://[a-zA-Z0-9-.]+(:[1-9][0-9]{0,4})?((?...required

The value of the iss claim as returned by this provider. Must be unique within the root project.

Example:"https://example.com/oidc"
revstring(ResourceRev)^.*$required

An opaque string that represents the revision of a given resource. Each time the resource is updated, this value changes.

Example:"abc123"
updatedBystring(UpdatedBy)^.*$

A string indicating the principal who last invoked an operation to update the resource.

Example:"principal:ABCD-EFG-12345:idp:example-user"
statusstring(ProviderStatus)required
  • "ENABLED": the provider is trusted, and token exchange is enabled
    • "SUSPENDED": token exchange for ID tokens from this provider is currently disabled
Enum:"ENABLED""SUSPENDED"
Example:"ENABLED"
groupMembershipClaimstring, [ 2 .. 100 ] characters

Name of the claim in the ID tokens provided by this OIDC issuer whose value the STS should interpret as containing a user's group memberships, for authorization purposes. The value of the group membership claim in an ID token must be an array of strings, where each string is a unique, non-reassignable identifier for a group. When this property is not set, the STS does not interpret any claim from this provider as a group membership claim.

Example:"groups"
trustedClientIdsArray of strings, [ 0 .. 10 ] itemsrequired

List of OAuth 2.0 client ids for this provider that are permitted to exchange ID tokens for access tokens. The value of the aud claim in an ID token is checked against this list during token exchange.

jwksRetrievedAtstringrequired

Timestamp string formatted like: "2025-02-13T17:10:00.864707507Z".

Example:"2025-02-13T17:10:00.864707507Z"
Response
{
  "jwks": {
    "keys": [ … ]
  },
  "idpId": "idp:my-idp",
  "updatedAt": "2024-01-15T12:00:00Z",
  "createdBy": "principal:ABCD-EFG-12345:idp:example-user",
  "issuerLocation": "https://example.com/oidc",
  "name": "My OIDC Provider",
  "createdAt": "2024-01-15T12:00:00Z",
  "issuerUri": "https://example.com/oidc",
  "rev": "abc123",
  "updatedBy": "principal:ABCD-EFG-12345:idp:example-user",
  "status": "ENABLED",
  "groupMembershipClaim": "groups",
  "trustedClientIds": [
    "my-oauth-client-id"
  ],
  "jwksRetrievedAt": "2025-02-13T17:10:00.864707507Z"
}
Was this page helpful?