openapi: 3.0.1 info: title: Authorization API Specification description: This specification describes the endpoints of the Authorization service version: 0-SNAPSHOT servers: - url: http://localhost description: local development host tags: - name: Authorization Discovery description: Login and issue token support functions - name: Token Management description: Management functions for tokens - name: OpenID Connect description: OpenID Connect support functions for verification of tokens paths: /authorization/v1/.well-known/jwks.json: get: tags: - OpenID Connect summary: Get well known jwks description: "Reads well known jwks, used for token verification" operationId: getWellKnownJwks responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/JwksV1' /authorization/v1/.well-known/openid-configuration: get: tags: - OpenID Connect summary: Get OpenIdConnect Discovery description: Reads OpenIdConnect Discovery meta information operationId: getDiscoveryInfo responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/OpenIdConnectDiscoveryV1' /authorization/v1/applications/{application-expression}/tenant-actor-affiliations: get: tags: - Authorization Discovery summary: Get tenant actor affiliations description: Reads available tenant actor affiliations for given application where the calling subject may issue a token operationId: getTenantActorAffiliations parameters: - $ref: '#/components/parameters/application-expression' responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/TenantActorAffiliationV1' application/x-ndjson: schema: type: array items: $ref: '#/components/schemas/TenantActorAffiliationV1' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' security: - external-token: [] /authorization/v1/tenants/{tenant-expression}/tokens: post: tags: - Token Management summary: Issue tenant token description: |- Creates a new tenant token for the actor in specified tenant with the given subject authentication. The payload format of the jwk is specified in IamJwtPayloadT1. operationId: createTenantToken parameters: - $ref: '#/components/parameters/tenant-expression' requestBody: content: application/json: schema: $ref: '#/components/schemas/TenantTokenInV1' required: true responses: "200": description: OK content: application/jwt: schema: type: string "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: - external-token: [] /authorization/v1/tenants/{tenant-expression}/tokens/{token-set-expression}: delete: tags: - Token Management summary: Revoke tenant token by expression description: Mark tenant token(s) by expression as revoked operationId: revokeTenantTokens parameters: - $ref: '#/components/parameters/tenant-expression' - $ref: '#/components/parameters/token-set-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-tenant-token: [] components: schemas: AccessRefSetV1: required: - r type: object properties: r: type: array description: State given role(s) for the subject and any resource accesses for said role(s) items: type: string description: "The identifier of a role, also know as 'roleKey'" example: ADMINISTRATOR a: type: array description: States which actor resources that are available for the given role items: type: string description: The globally unique identifier for an actor "n": type: array description: States which node resources that are available for the given role items: type: string description: The globally unique identifier for a node c: type: array description: States which custom resources that are available for the given role items: maxLength: 193 minLength: 3 pattern: "^[a-zA-Z0-9-_.]{1,64}=.{1,128}$" type: string description: A custom identifier for an entity in its flat format. example: VIN=5GZCZ43D13S812715 description: Access reference sets for this token ErrorDetailV1: required: - code type: object properties: field: type: string description: A reference to a field or parameter which cannot be processed code: type: string description: "A code which indicated the type of error, documented per service" message: type: string description: "Additional information, intended for developers" description: "Additional error details, usually used for form validation. Documented\ \ per service and endpoint." ErrorV1: required: - errorId 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. message: type: string description: A human readable message of error. Intended for developers. details: type: array description: "Additional error details, usually used for form validation.\ \ Documented per service and endpoint." items: $ref: '#/components/schemas/ErrorDetailV1' IamJwtPayloadT1: required: - acc - app - aud - exp - iat - iss - jti - sub - tid type: object properties: jti: type: string description: JWT identifier iss: type: string description: "Identifies the issuer, which is the principal/system/application\ \ that issued the jwt" sub: type: string description: The globally unique identifier for an actor aud: type: string description: Identifies the recipients that the JWT is intended for exp: type: integer description: Identifies the expiration time on and after which the JWT must not be accepted for processing format: int64 nbf: type: integer description: Identifies the time on which the JWT will start to be accepted for processing format: int64 iat: type: integer description: Identifies the time at which the JWT was issued format: int64 acc: type: string description: The globally unique identifier for an account app: type: string description: The globally unique identifier for an application tid: type: string description: The globally unique identifier for a tenant ars: type: array description: Access reference sets for this token items: $ref: '#/components/schemas/AccessRefSetV1' JwkV1: required: - e - kid - kty - "n" - use type: object properties: kid: type: string description: Key Id (thumbprint) kty: type: string description: Key type. Will be 'RSA' use: type: string description: Usage. Will be 'sig' "n": type: string description: Modulus e: type: string description: Public exponent description: A list of jwks that are applicable for a certain system JwksV1: required: - keys type: object properties: keys: type: array description: A list of jwks that are applicable for a certain system items: $ref: '#/components/schemas/JwkV1' OpenIdConnectDiscoveryV1: required: - authorization_endpoint - id_token_signing_alg_values_supported - issuer - jwks_uri - subject_types_supported type: object properties: issuer: type: string description: "URL using the https scheme with no query or fragment component\ \ that the OP asserts as its Issuer Identifier. If Issuer discovery is\ \ supported (see Section 2), this value MUST be identical to the issuer\ \ value returned by WebFinger. This also MUST be identical to the iss\ \ Claim value in ID Tokens issued from this Issuer" authorization_endpoint: type: string description: "URL of the OP's OAuth 2.0 Authorization Endpoint [OpenID.Core]." token_endpoint: type: string description: "URL of the OP's OAuth 2.0 Token Endpoint [OpenID.Core]. This\ \ is REQUIRED unless only the Implicit Flow is used." userinfo_endpoint: type: string description: "URL of the OP's UserInfo Endpoint [OpenID.Core]. This URL\ \ MUST use the https scheme and MAY contain port, path, and query parameter\ \ components." jwks_uri: type: string description: "URL of the OP's JSON Web Key Set [JWK] document. This contains\ \ the signing key(s) the RP uses to validate signatures from the OP. The\ \ JWK Set MAY also contain the Server's encryption key(s), which are used\ \ by RPs to encrypt requests to the Server. When both signing and encryption\ \ keys are made available, a use (Key Use) parameter value is REQUIRED\ \ for all keys in the referenced JWK Set to indicate each key's intended\ \ usage. Although some algorithms allow the same key to be used for both\ \ signatures and encryption, doing so is NOT RECOMMENDED, as it is less\ \ secure. The JWK x5c parameter MAY be used to provide X.509 representations\ \ of keys provided. When used, the bare key values MUST still be present\ \ and MUST match those in the certificate." registration_endpoint: type: string description: "URL of the OP's Dynamic Client Registration Endpoint [OpenID.Registration]." scopes_supported: type: array description: "JSON array containing a list of the OAuth 2.0 [RFC6749] scope\ \ values that this server supports. The server MUST support the openid\ \ scope value. Servers MAY choose not to advertise some supported scope\ \ values even when this parameter is used, although those defined in [OpenID.Core]\ \ SHOULD be listed, if supported." items: type: string description: "JSON array containing a list of the OAuth 2.0 [RFC6749]\ \ scope values that this server supports. The server MUST support the\ \ openid scope value. Servers MAY choose not to advertise some supported\ \ scope values even when this parameter is used, although those defined\ \ in [OpenID.Core] SHOULD be listed, if supported." response_types_supported: type: array description: "JSON array containing a list of the OAuth 2.0 response_type\ \ values that this OP supports. Dynamic OpenID Providers MUST support\ \ the code, id_token, and the token id_token Response Type values." items: type: string description: "JSON array containing a list of the OAuth 2.0 response_type\ \ values that this OP supports. Dynamic OpenID Providers MUST support\ \ the code, id_token, and the token id_token Response Type values." response_modes_supported: type: array description: "JSON array containing a list of the OAuth 2.0 response_mode\ \ values that this OP supports, as specified in OAuth 2.0 Multiple Response\ \ Type Encoding Practices [OAuth.Responses]. If omitted, the default for\ \ Dynamic OpenID Providers is [\"query\", \"fragment\"]." items: type: string description: "JSON array containing a list of the OAuth 2.0 response_mode\ \ values that this OP supports, as specified in OAuth 2.0 Multiple Response\ \ Type Encoding Practices [OAuth.Responses]. If omitted, the default\ \ for Dynamic OpenID Providers is [\"query\", \"fragment\"]." grant_types_supported: type: array description: "JSON array containing a list of the OAuth 2.0 Grant Type values\ \ that this OP supports. Dynamic OpenID Providers MUST support the authorization_code\ \ and implicit Grant Type values and MAY support other Grant Types. If\ \ omitted, the default value is [\"authorization_code\", \"implicit\"\ ]." items: type: string description: "JSON array containing a list of the OAuth 2.0 Grant Type\ \ values that this OP supports. Dynamic OpenID Providers MUST support\ \ the authorization_code and implicit Grant Type values and MAY support\ \ other Grant Types. If omitted, the default value is [\"authorization_code\"\ , \"implicit\"]." acr_values_supported: type: array description: JSON array containing a list of the Authentication Context Class References that this OP supports. items: type: string description: JSON array containing a list of the Authentication Context Class References that this OP supports. subject_types_supported: type: array description: JSON array containing a list of the Subject Identifier types that this OP supports. Valid types include pairwise and public. items: type: string description: JSON array containing a list of the Subject Identifier types that this OP supports. Valid types include pairwise and public. id_token_signing_alg_values_supported: type: array description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]. The algorithm RS256 MUST be included. The value none\ \ MAY be supported, but MUST NOT be used unless the Response Type used\ \ returns no ID Token from the Authorization Endpoint (such as when using\ \ the Authorization Code Flow)." items: type: string description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]. The algorithm RS256 MUST be included. The value none\ \ MAY be supported, but MUST NOT be used unless the Response Type used\ \ returns no ID Token from the Authorization Endpoint (such as when\ \ using the Authorization Code Flow)." id_token_encryption_alg_values_supported: type: array description: "JSON array containing a list of the JWE encryption algorithms\ \ (alg values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]." items: type: string description: "JSON array containing a list of the JWE encryption algorithms\ \ (alg values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]." id_token_encryption_enc_values_supported: type: array description: "JSON array containing a list of the JWE encryption algorithms\ \ (enc values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]." items: type: string description: "JSON array containing a list of the JWE encryption algorithms\ \ (enc values) supported by the OP for the ID Token to encode the Claims\ \ in a JWT [JWT]." userinfo_signing_alg_values_supported: type: array description: "JSON array containing a list of the JWS [JWS] signing algorithms\ \ (alg values) [JWA] supported by the UserInfo Endpoint to encode the\ \ Claims in a JWT [JWT]. The value none MAY be included." items: type: string description: "JSON array containing a list of the JWS [JWS] signing algorithms\ \ (alg values) [JWA] supported by the UserInfo Endpoint to encode the\ \ Claims in a JWT [JWT]. The value none MAY be included." userinfo_encryption_alg_values_supported: type: array description: "JSON array containing a list of the JWE [JWE] encryption algorithms\ \ (alg values) [JWA] supported by the UserInfo Endpoint to encode the\ \ Claims in a JWT [JWT]." items: type: string description: "JSON array containing a list of the JWE [JWE] encryption\ \ algorithms (alg values) [JWA] supported by the UserInfo Endpoint to\ \ encode the Claims in a JWT [JWT]." userinfo_encryption_enc_values_supported: type: array description: "JSON array containing a list of the JWE encryption algorithms\ \ (enc values) [JWA] supported by the UserInfo Endpoint to encode the\ \ Claims in a JWT [JWT]." items: type: string description: "JSON array containing a list of the JWE encryption algorithms\ \ (enc values) [JWA] supported by the UserInfo Endpoint to encode the\ \ Claims in a JWT [JWT]." request_object_signing_alg_values_supported: type: array description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the OP for Request Objects, which are described\ \ in Section 6.1 of OpenID Connect Core 1.0 [OpenID.Core]. These algorithms\ \ are used both when the Request Object is passed by value (using the\ \ request parameter) and when it is passed by reference (using the request_uri\ \ parameter). Servers SHOULD support none and RS256." items: type: string description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the OP for Request Objects, which are described\ \ in Section 6.1 of OpenID Connect Core 1.0 [OpenID.Core]. These algorithms\ \ are used both when the Request Object is passed by value (using the\ \ request parameter) and when it is passed by reference (using the request_uri\ \ parameter). Servers SHOULD support none and RS256." request_object_encryption_alg_values_supported: type: array description: JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference. items: type: string description: JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference. request_object_encryption_enc_values_supported: type: array description: JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference. items: type: string description: JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference. token_endpoint_auth_methods_supported: type: array description: "JSON array containing a list of Client Authentication methods\ \ supported by this Token Endpoint. The options are client_secret_post,\ \ client_secret_basic, client_secret_jwt, and private_key_jwt, as described\ \ in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. Other authentication\ \ methods MAY be defined by extensions. If omitted, the default is client_secret_basic\ \ -- the HTTP Basic Authentication Scheme specified in Section 2.3.1 of\ \ OAuth 2.0 [RFC6749]." items: type: string description: "JSON array containing a list of Client Authentication methods\ \ supported by this Token Endpoint. The options are client_secret_post,\ \ client_secret_basic, client_secret_jwt, and private_key_jwt, as described\ \ in Section 9 of OpenID Connect Core 1.0 [OpenID.Core]. Other authentication\ \ methods MAY be defined by extensions. If omitted, the default is client_secret_basic\ \ -- the HTTP Basic Authentication Scheme specified in Section 2.3.1\ \ of OAuth 2.0 [RFC6749]." token_endpoint_auth_signing_alg_values_supported: type: array description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the Token Endpoint for the signature on the\ \ JWT [JWT] used to authenticate the Client at the Token Endpoint for\ \ the private_key_jwt and client_secret_jwt authentication methods. Servers\ \ SHOULD support RS256. The value none MUST NOT be used." items: type: string description: "JSON array containing a list of the JWS signing algorithms\ \ (alg values) supported by the Token Endpoint for the signature on\ \ the JWT [JWT] used to authenticate the Client at the Token Endpoint\ \ for the private_key_jwt and client_secret_jwt authentication methods.\ \ Servers SHOULD support RS256. The value none MUST NOT be used." display_values_supported: type: array description: "JSON array containing a list of the display parameter values\ \ that the OpenID Provider supports. These values are described in Section\ \ 3.1.2.1 of OpenID Connect Core 1.0 [OpenID.Core]." items: type: string description: "JSON array containing a list of the display parameter values\ \ that the OpenID Provider supports. These values are described in Section\ \ 3.1.2.1 of OpenID Connect Core 1.0 [OpenID.Core]." claim_types_supported: type: array description: "JSON array containing a list of the Claim Types that the OpenID\ \ Provider supports. These Claim Types are described in Section 5.6 of\ \ OpenID Connect Core 1.0 [OpenID.Core]. Values defined by this specification\ \ are normal, aggregated, and distributed. If omitted, the implementation\ \ supports only normal Claims." items: type: string description: "JSON array containing a list of the Claim Types that the\ \ OpenID Provider supports. These Claim Types are described in Section\ \ 5.6 of OpenID Connect Core 1.0 [OpenID.Core]. Values defined by this\ \ specification are normal, aggregated, and distributed. If omitted,\ \ the implementation supports only normal Claims." claims_supported: type: array description: "JSON array containing a list of the Claim Names of the Claims\ \ that the OpenID Provider MAY be able to supply values for. Note that\ \ for privacy or other reasons, this might not be an exhaustive list." items: type: string description: "JSON array containing a list of the Claim Names of the Claims\ \ that the OpenID Provider MAY be able to supply values for. Note that\ \ for privacy or other reasons, this might not be an exhaustive list." service_documentation: type: string description: "URL of a page containing human-readable information that developers\ \ might want or need to know when using the OpenID Provider. In particular,\ \ if the OpenID Provider does not support Dynamic Client Registration,\ \ then information on how to register Clients needs to be provided in\ \ this documentation." claims_locales_supported: type: array description: "Languages and scripts supported for values in Claims being\ \ returned, represented as a JSON array of BCP47 [RFC5646] language tag\ \ values. Not all languages and scripts are necessarily supported for\ \ all Claim values." items: type: string description: "Languages and scripts supported for values in Claims being\ \ returned, represented as a JSON array of BCP47 [RFC5646] language\ \ tag values. Not all languages and scripts are necessarily supported\ \ for all Claim values." ui_locales_supported: type: array description: "Languages and scripts supported for the user interface, represented\ \ as a JSON array of BCP47 [RFC5646] language tag values." items: type: string description: "Languages and scripts supported for the user interface,\ \ represented as a JSON array of BCP47 [RFC5646] language tag values." claims_parameter_supported: type: string description: "Boolean value specifying whether the OP supports use of the\ \ claims parameter, with true indicating support. If omitted, the default\ \ value is false." request_parameter_supported: type: string description: "Boolean value specifying whether the OP supports use of the\ \ request parameter, with true indicating support. If omitted, the default\ \ value is false." request_uri_parameter_supported: type: string description: "Boolean value specifying whether the OP supports use of the\ \ request_uri parameter, with true indicating support. If omitted, the\ \ default value is true." require_request_uri_registration: type: string description: "Boolean value specifying whether the OP requires any request_uri\ \ values used to be pre-registered using the request_uris registration\ \ parameter. Pre-registration is REQUIRED when the value is true. If omitted,\ \ the default value is false." op_policy_uri: type: string description: URL that the OpenID Provider provides to the person registering the Client to read about the OP's requirements on how the Relying Party can use the data provided by the OP. The registration process SHOULD display this URL to the person registering the Client if it is given. op_tos_uri: type: string description: URL that the OpenID Provider provides to the person registering the Client to read about OpenID Provider's terms of service. The registration process SHOULD display this URL to the person registering the Client if it is given. TenantActorAccessV1: required: - role type: object properties: role: type: string description: "The identifier of a role, also know as 'roleKey'" example: ADMINISTRATOR description: Assigned accesses for the actor TenantActorAffiliationV1: required: - accountId - actorId - actorStatus - actorType - applicationId - tenantId type: object properties: accountId: type: string description: The globally unique identifier for an account accountName: type: string description: The display name of the account applicationId: type: string description: The globally unique identifier for an application applicationName: type: string description: The display name of the account tenantId: type: string description: The globally unique identifier for a tenant tenantName: type: string description: The display name of the tenant actorId: type: string description: The globally unique identifier for an actor actorName: type: string description: "A name, usually for an entity" example: John Doe actorType: type: string description: "The actor type. Used to distinguish different variants and\ \ to tie configurations, permissions and rules." example: "PERSON, DEVICE" actorStatus: type: string description: A status value example: Operational actorAccesses: type: array description: Assigned accesses for the actor items: $ref: '#/components/schemas/TenantActorAccessV1' actorIdpAffiliations: type: array description: Assigned idp affiliations for the actor items: $ref: '#/components/schemas/TenantActorIdpAffiliationV1' TenantActorIdpAffiliationV1: required: - idpKey type: object properties: idpKey: type: string description: An identity provider key which is used to identity a specific identity provider configuration. username: type: string description: The username of a subject for an identity provider. Usually an email address or AD name. Used when the 'subject' is not known. description: Assigned idp affiliations for the actor TenantTokenInV1: required: - tokenFormat type: object properties: tokenFormat: type: string description: The returned format of the token enum: - t1 expiryInSecs: type: integer description: The wanted expiry time of the token. May be restricted by configuration. This value is optional and a default value defined by the server will be used if omitted. format: int32 responses: 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" tenant-expression: name: tenant-expression in: path required: true schema: pattern: "^[a-zA-Z0-9-_.]{1,64}$" type: string description: "Used to identify a specific tenantId. The available options\ \ are: \n* '{tenantId}' - direct tenantId reference" token-set-expression: name: token-set-expression in: path required: true schema: pattern: "^tokenId=[a-zA-Z0-9-_&|#%=?<>\\\\.\\/:;,!\\[\\]\\(\\)]{1,128}$|^mine$|^current$" type: string description: "Used to identify a specific token or a range of tokens. The\ \ available options are: \ntokenId: reference token by given tokenId\nmine:\ \ references all tokens issued by actor with the given jwt token\ncurrent:\ \ reference the provided jwt token" securitySchemes: external-token: type: http scheme: bearer bearerFormat: External token issued by a trusted identity provider iam-tenant-token: type: http scheme: bearer bearerFormat: IAM issued jwt token for a generic application