openapi: 3.0.1 info: title: IAM Identity Provider Management API Specification description: This specification describes the endpoints of the IAM Identity Provider Management Service. version: 0-SNAPSHOT servers: - url: http://localhost description: local development host tags: - name: IAM Identity Provider Discovery description: Support functions for reading identity provider configuration - name: IAM Console Application Identity Provider Management description: Management functions for application identity provider configurations in IAM Console paths: /idp/v1/applications/{application-expression}/identity-providers: get: tags: - IAM Console Application Identity Provider Management summary: Get application identity providers description: Read application identity providers by application expression operationId: getApplicationIdentityProviders parameters: - $ref: "#/components/parameters/application-expression" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - iam-console-token: [] put: tags: - IAM Console Application Identity Provider Management summary: Upsert application identity providers description: Create or replace a specific application identity providers for the referenced application. If an empty list is given as input then any exising configurations will be removed. operationId: upsertApplicationIdentityProviders parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/returnUpdated" requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderInV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderInV1" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderV1" application/x-ndjson: schema: type: array items: $ref: "#/components/schemas/ApplicationIdentityProviderV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] delete: tags: - IAM Console Application Identity Provider Management summary: Delete application identity providers description: Remove application identity providers by application expression operationId: deleteApplicationIdentityProviders parameters: - $ref: "#/components/parameters/application-expression" responses: "204": description: The request is processed and no content was returned "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] /idp/v1/applications/{application-expression}/identity-providers/{identity-provider-key}: get: tags: - IAM Console Application Identity Provider Management summary: Get application identity provider description: Read application identity provider by application expression and identity provider key operationId: getApplicationIdentityProvider parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/identity-provider-key" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ApplicationIdentityProviderV1" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - iam-console-token: [] put: tags: - IAM Console Application Identity Provider Management summary: Upsert application identity provider description: Create or replace a specific application identity provider for the referenced application operationId: upsertApplicationIdentityProvider parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/identity-provider-key" - $ref: "#/components/parameters/returnUpdated" requestBody: content: application/json: schema: $ref: "#/components/schemas/ApplicationIdentityProviderInWithoutKeyV1" required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ApplicationIdentityProviderV1" "204": $ref: "#/components/responses/NoContent" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] delete: tags: - IAM Console Application Identity Provider Management summary: Delete application identity provider description: Remove application identity provider by application expression and identity provider key operationId: deleteApplicationIdentityProvider parameters: - $ref: "#/components/parameters/application-expression" - $ref: "#/components/parameters/identity-provider-key" responses: "204": description: The request is processed and no content was returned "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" security: - iam-console-token: [] /idp/v1/applications/{application-expression}/public-identity-provider-setup: get: tags: - IAM Identity Provider Discovery summary: Get publicly declared application identity providers description: Read public declared identity provider definitions for the given application expression operationId: getPublicIdentityProviderSetup parameters: - $ref: "#/components/parameters/application-expression" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/IdentityProviderSetupV1" application/x-ndjson: schema: $ref: "#/components/schemas/IdentityProviderSetupV1" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" /idp/v1/identity-provider-setup: get: tags: - IAM Identity Provider Discovery summary: Get application defined identity providers description: Read identity provider setup for the current application operationId: getIdentityProviderSetup responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/IdentityProviderSetupV1" application/x-ndjson: schema: $ref: "#/components/schemas/IdentityProviderSetupV1" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" security: - iam-console-token: [] components: schemas: ApplicationIdentityProviderInV1: required: - key - status - subjectPoolKey - type - visibility type: object properties: key: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: An identity provider key which is used to identity a specific identity provider configuration. example: idp-1 subjectPoolKey: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: The subject pool identifies the database where the end user is stored. Primarily used where multiple oauth or oidc configurations are used but the origin of the user is the same. example: cognito-pool-1 name: maxLength: 64 type: string description: "A name, usually for an entity" example: John Doe description: maxLength: 4096 type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." type: type: string description: "Reference a support identity provider implementation. Depending\ \ on the type, additional configuration may be required." enum: - OAUTH2_IMPLICIT - OAUTH2_AUTH_CODE - OIDC status: type: string description: The initial status of this idp configuration enum: - ENABLED - DISABLED oauth2Config: $ref: "#/components/schemas/IdpOauth2ConfigInV1" oidcConfig: $ref: "#/components/schemas/IdpOidcConfigInV1" visibility: type: string description: Defined how and if this configuration is made available via idp discovery endpoints. enum: - APPLICATION - PUBLIC - HIDDEN additionalConfigEntries: maxItems: 20 minItems: 0 type: array description: A set of additional configuration entries that may be relevant the end user when completing the authentication flow. items: $ref: "#/components/schemas/IdpConfigEntryIn" description: A trusted identity provider configuration which can be used for authenticating end users. ApplicationIdentityProviderInWithoutKeyV1: required: - status - subjectPoolKey - type - visibility type: object properties: subjectPoolKey: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: The subject pool identifies the database where the end user is stored. Primarily used where multiple oauth or oidc configurations are used but the origin of the user is the same. example: cognito-pool-1 name: maxLength: 64 type: string description: "A name, usually for an entity" example: John Doe description: maxLength: 4096 type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." type: type: string description: "Reference a support identity provider implementation. Depending\ \ on the type, additional configuration may be required." enum: - OAUTH2_IMPLICIT - OAUTH2_AUTH_CODE - OIDC status: type: string description: The initial status of this idp configuration enum: - ENABLED - DISABLED oauth2Config: $ref: "#/components/schemas/IdpOauth2ConfigInV1" oidcConfig: $ref: "#/components/schemas/IdpOidcConfigInV1" visibility: type: string description: Defined how and if this configuration is made available via idp discovery endpoints. enum: - APPLICATION - PUBLIC - HIDDEN additionalConfigEntries: maxItems: 20 minItems: 0 type: array description: A set of additional configuration entries that may be relevant the end user when completing the authentication flow. items: $ref: "#/components/schemas/IdpConfigEntryIn" description: A trusted identity provider configuration which can be used for authenticating end users. ApplicationIdentityProviderV1: required: - applicationId - changeId - createdAt - createdBy - key - lastModifiedAt - lastModifiedBy - status - subjectPoolKey - type - visibility type: object properties: applicationId: type: string description: The globally unique identifier for an application key: type: string description: An identity provider key which is used to identity a specific identity provider configuration. subjectPoolKey: type: string description: The subject pool identifies the database where the end user is stored. Primarily used where multiple oauth or oidc configurations are used but the origin of the user is the same. name: type: string description: "A name, usually for an entity" example: John Doe description: type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." type: type: string description: "Reference a support identity provider implementation. Depending\ \ on the type, additional configuration may be required." status: type: string description: The status of this idp configuration oauth2Config: $ref: "#/components/schemas/IdpOauth2ConfigV1" oidcConfig: $ref: "#/components/schemas/IdpOidcConfigV1" visibility: type: string description: Defined how and if this configuration is made available via idp discovery endpoints. additionalConfigEntries: type: array description: A set of additional configuration entries that may be relevant the end user when completing the authentication flow. items: $ref: "#/components/schemas/IdpConfigEntry" createdAt: type: string description: UTC date time when entity was created. This string is formatted according to RFC3339. format: date-time createdBy: type: string description: The globally unique identifier for an actor lastModifiedAt: type: string description: UTC date time when entity was modified. This string is formatted according to RFC3339. format: date-time lastModifiedBy: type: string description: The globally unique identifier for an actor changeId: type: string description: Text representation of changeId sequence number example: "7380283282446876762" description: A trusted identity provider configuration which can be used for authenticating end users. ErrorDetailV1: type: object properties: field: type: string description: A reference to a field or parameter which cannot be processed. value: type: string description: The value which could not be processed. message: type: string description: A human readable message of error. Intended for developers. description: 'Additional information about the error ' ErrorV1: required: - errorId - occurredAt type: object properties: errorId: type: string description: "An error identifier for the request, to be provided in troubleshooting." code: type: string description: |- An error code which describes this error. Documented per service and endpoint. See respective ErrorCodeRegistry DTO for possible error codes. message: type: string description: A human readable message of error. Intended for developers. details: type: array description: Additional information about the error which can be used in troubleshooting. items: $ref: "#/components/schemas/ErrorDetailV1" occurredAt: type: string description: The timestamp when the error occurred. This string is formatted according to RFC3339. format: date-time IamIdpErrorCodeRegistryV1: type: object properties: getPublicIdentityProviderSetup: type: string enum: - INPUT_MALFORMED getIdentityProviderSetup: type: string enum: - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED upsertApplicationIdentityProvider: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHENTICATION_IDP_CONFIG_MALFORMED - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND upsertApplicationIdentityProviders: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHENTICATION_IDP_CONFIG_MALFORMED - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND getApplicationIdentityProvider: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND - IAM_IDP_NOT_FOUND getApplicationIdentityProviders: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND deleteApplicationIdentityProvider: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND deleteApplicationIdentityProviders: type: string enum: - INPUT_MALFORMED - AUTHENTICATION_FAILED - AUTHENTICATION_EXPIRED - AUTHENTICATION_REVOKED - AUTHENTICATION_INVALID_APPLICATION - AUTHORIZATION_MISSING_PERMISSION - IAM_APPLICATION_NOT_FOUND description: |- This entry describes possible error codes that may be returned by their respective operation. These can be used to apply logic upon receiving an error response. IdentityProviderSetupV1: required: - applicationId - changeId type: object properties: applicationId: type: string description: The globally unique identifier for an application identityProviders: type: array description: Identity provider configurations for this application items: $ref: "#/components/schemas/IdentityProviderV1" changeId: type: string description: Text representation of changeId sequence number example: "7380283282446876762" description: A set of trusted identity provider configuration which can be used for authenticating end users. IdentityProviderV1: required: - key - subjectPoolKey - type type: object properties: key: type: string description: An identity provider key which is used to identity a specific identity provider configuration. subjectPoolKey: type: string description: The subject pool identifies the database where the end user is stored. Primarily used where multiple oauth or oidc configurations are used but the origin of the user is the same. name: type: string description: "A name, usually for an entity" example: John Doe description: type: string description: "A description, usually for an entity" example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit." type: type: string description: "Reference a support identity provider implementation. Depending\ \ on the type, additional configuration may be required." oauth2Details: $ref: "#/components/schemas/IdpOauth2DetailsV1" oidcDetails: $ref: "#/components/schemas/IdpOidcDetailsV1" additionalConfigEntries: type: array description: A set of additional configuration entries that may be relevant the end user when completing the authentication flow. items: $ref: "#/components/schemas/IdpConfigEntry" description: Basic details of a trusted identity provider. IdpAttributeMappingClientIdInV1: required: - attribute type: object properties: attribute: maxLength: 256 minLength: 1 type: string description: Reference to the client_id attribute description: Reference to the attribute which represents the client_id when requesting a token. IdpAttributeMappingClientIdV1: required: - attribute type: object properties: attribute: type: string description: Reference to the client_id attribute description: Reference to the attribute which represents the client_id when requesting a token. IdpAttributeMappingNameInV1: required: - attribute - syncOption type: object properties: attribute: maxLength: 256 minLength: 1 type: string description: Reference to the name attribute syncOption: type: string description: Defines if any mapped name should be copied into the associated actor enum: - NEVER - ONCE - ALWAYS description: Reference to the attribute which represents the name of the end user. IdpAttributeMappingNameV1: required: - attribute - syncOption type: object properties: attribute: type: string description: Reference to the name attribute syncOption: type: string description: Defines if any mapped name should be copied into the associated actor description: Reference to the attribute which represents the name of the end user. IdpAttributeMappingSubjectInV1: required: - attribute type: object properties: attribute: maxLength: 256 minLength: 1 type: string description: Reference to the subject id attribute description: Reference to the attribute which represents the subject id of the end user. IdpAttributeMappingSubjectV1: required: - attribute type: object properties: attribute: type: string description: Reference to the subject id attribute description: Reference to the attribute which represents the subject id of the end user. IdpAttributeMappingUsernameInV1: required: - attribute type: object properties: attribute: maxLength: 256 minLength: 1 type: string description: Reference to the username attribute. description: Reference to the attribute which represents the username of the subject for for its identity provider. The referenced value should be unique for the identity provider instance. IdpAttributeMappingUsernameV1: required: - attribute type: object properties: attribute: type: string description: Reference to the username attribute. description: Reference to the attribute which represents the username of the subject for for its identity provider. The referenced value should be unique for the identity provider instance. IdpConfigEntry: required: - type - value type: object properties: type: type: string description: The type of the configuration entry value: type: string description: The value of the configuration entry description: A customer defined configuration entry for an identity provider. Used to share public configuration details. IdpConfigEntryIn: required: - type - value type: object properties: type: maxLength: 256 minLength: 1 type: string description: The type of the configuration entry value: maxLength: 256 minLength: 1 type: string description: The value of the configuration entry description: A customer defined configuration entry for an identity provider. Used to share public configuration details. IdpOauth2ConfigInV1: required: - subjectMapping - userInfoUrl type: object properties: clientId: maxLength: 256 minLength: 0 type: string description: The public identifier for the oauth application clientSecret: maxLength: 256 minLength: 0 type: string description: A secret key that is used to authenticate the backend call to the oauth server for this oauth application authorizeUrl: maxLength: 256 type: string description: "The URL to use to initiate the authorization code grant flow,\ \ usually a login page for the end user." example: https://accounts.google.com/o/oauth2/v2/auth tokenUrl: maxLength: 256 type: string description: The URL to use to obtain an access token using the authorization code grant flow or to refresh the token. example: https://oauth2.googleapis.com/token userInfoUrl: maxLength: 256 minLength: 1 type: string description: The URL to use to basic user information. Used to validate the access token and extract subject id. example: https://openidconnect.googleapis.com/v1/userinfo clientIdMapping: $ref: "#/components/schemas/IdpAttributeMappingClientIdInV1" subjectMapping: $ref: "#/components/schemas/IdpAttributeMappingSubjectInV1" usernameMapping: $ref: "#/components/schemas/IdpAttributeMappingUsernameInV1" nameMapping: $ref: "#/components/schemas/IdpAttributeMappingNameInV1" description: OAuth2 configuration options. IdpOauth2ConfigV1: required: - subjectMapping - userInfoUrl type: object properties: clientId: type: string description: The public identifier for the oauth application clientSecret: type: string description: A secret key that is used to authenticate the backend call to the oauth server for this oauth application authorizeUrl: type: string description: "The URL to use to initiate the authorization code grant flow,\ \ usually a login page for the end user." tokenUrl: type: string description: The URL to use to obtain an access token using the authorization code grant flow or to refresh the token. userInfoUrl: type: string description: The URL to use to basic user information. Used to validate the access token and extract subject id. clientIdMapping: $ref: "#/components/schemas/IdpAttributeMappingClientIdV1" subjectMapping: $ref: "#/components/schemas/IdpAttributeMappingSubjectV1" usernameMapping: $ref: "#/components/schemas/IdpAttributeMappingUsernameV1" nameMapping: $ref: "#/components/schemas/IdpAttributeMappingNameV1" description: OAuth2 configuration options. IdpOauth2DetailsV1: required: - userInfoUrl type: object properties: clientId: type: string description: The public identifier for the oauth application authorizeUrl: type: string description: "The URL to use to initiate the authorization code grant flow,\ \ usually a login page for the end user." userInfoUrl: type: string description: The URL to use to basic user information. Used to validate the access token and extract subject id. description: OAuth2 details IdpOidcConfigInV1: required: - audience - issuer type: object properties: issuer: maxLength: 256 minLength: 1 type: string description: "Identifies the issuer, which is the principal/system/application\ \ that issued the jwt. Must be a valid URL and its oidc configuration\ \ must be present at the standardized .well-known/openid-configuration\ \ location." audience: maxLength: 256 minLength: 1 type: string description: Identifies the recipients that the JWT is intended for. Will be used in validation of a given JWT. usernameMapping: $ref: "#/components/schemas/IdpAttributeMappingUsernameInV1" nameMapping: $ref: "#/components/schemas/IdpAttributeMappingNameInV1" description: OIDC adapter configuration options. IdpOidcConfigV1: required: - audience - issuer type: object properties: issuer: type: string description: "Identifies the issuer, which is the principal/system/application\ \ that issued the jwt. Must be a valid URL and its oidc configuration\ \ must be present at the standardized .well-known/openid-configuration\ \ location." audience: type: string description: Identifies the recipients that the JWT is intended for. Will be used in validation of a given JWT. usernameMapping: $ref: "#/components/schemas/IdpAttributeMappingUsernameV1" nameMapping: $ref: "#/components/schemas/IdpAttributeMappingNameV1" description: OIDC adapter configuration options. IdpOidcDetailsV1: required: - audience - issuer type: object properties: issuer: type: string description: "Identifies the issuer, which is the principal/system/application\ \ that issued the jwt. Must be a valid URL and its oidc configuration\ \ must be present at the standardized .well-known/openid-configuration\ \ location." audience: type: string description: Identifies the recipients that the JWT is intended for. Will be used in validation of a given JWT. description: OIDC adapter details responses: NoContent: description: The request is processed and no content was returned BadRequest: description: "The request is malformed, see error data for additional information" content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Unauthorized: description: The request did not have valid authentication credentials content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Forbidden: description: The requester is not authorized to perform this action content: application/json: schema: $ref: "#/components/schemas/ErrorV1" NotFound: description: The resource could not be found content: application/json: schema: $ref: "#/components/schemas/ErrorV1" Conflict: description: "The request could not be processed due to a conflict in state,\ \ see error data for additional information" content: application/json: schema: $ref: "#/components/schemas/ErrorV1" parameters: application-expression: name: application-expression in: path required: true schema: pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: "Used to identify a specific applicationId. The available options\ \ are: \n* '{applicationId}' - direct applicationId reference" identity-provider-key: name: identity-provider-key in: path required: true schema: maxLength: 64 minLength: 1 pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: An identity provider key which is used to identity a specific identity provider configuration. example: idp-1 returnUpdated: name: returnUpdated in: query description: To return the entity after successful update or not schema: type: boolean default: false securitySchemes: iam-console-token: type: http scheme: bearer bearerFormat: IAM issued jwt token for the IAM console application iam-tenant-token: type: http scheme: bearer bearerFormat: IAM issued jwt token for a generic application