Details

openapi: 3.0.0 info: title: OAuth and OpenID Connect version: '0.0' servers: - url: 'https://{API_ENVIRONMENT}/a/consumer/api/v0' variables: API_ENVIRONMENT: default: digital.garden-fi.com description: FI specific hostname tags: - name: Provider Info - name: Token - name: Authorization - name: User Info paths: /oidc/.well-known/openid-configuration: get: tags: - Provider Info summary: Gets the provider configuration. description: See the [OpenID Connect Discovery specs](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/configResponse' '500': description: Internal Server Error /oidc/jwks: get: tags: - Provider Info summary: Gets the JSON Web Key Set (JWKS) for verifying JWTs received from the authentication server. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/certsResponse' '500': description: Internal Server Error /oidc/token: post: tags: - Token summary: Gets an access token. description: | This can be used to exchange an authorization code for an access token, or to [refresh an existing access token](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens). Note: The client_secret parameter is only required if your external application client type is 'confidential'. For 'public' external applications you should not provide the client_secret parameter. parameters: - name: DPoP in: header schema: type: string required: false description: | OPTIONAL: A valid Demonstrate Proof of Possession (DPoP) JWT used to bind the access token to the client. This is an advanced technique to prevent token theft. When an access token is bound, all API requests to a resource server must also present a valid DPoP header. requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/tokenRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/tokenResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/tokenFailure' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/tokenUnauthorized' '500': description: Internal Server Error /oidc/token/revocation: post: tags: - Token summary: Revokes a token. description: See the [OAuth Token Revocation specs](https://tools.ietf.org/html/rfc7009). parameters: - name: DPoP in: header schema: type: string required: false description: | OPTIONAL: A valid Demonstrate Proof of Possession (DPoP) JWT used to bind the access token to the client. This is an advanced technique to prevent token theft. When an access token is bound, all API requests to a resource server must also present a valid DPoP header. requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/tokenRevocationRequest' responses: '200': description: OK (no content) '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/tokenFailure' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/tokenUnauthorized' '500': description: Internal Server Error /oidc/auth: get: summary: Sends authentication request using query string parameters. description: 'Utilizing query string parameters, the `/auth` route will redirect to the specified `redirect_uri` with the result of the call found in the URL.' tags: - Authorization parameters: - name: response_type in: query description: The authorization type. Must be set to `code` required: true schema: type: string enum: - code example: code - name: client_id in: query description: ID of the client required: true schema: type: string example: 00000000-0000-0000-0000-000000000000 - name: redirect_uri in: query description: The redirect URI as registered by the client. required: false schema: type: string example: https://localhost/cb - name: scope in: query description: The possible scope of the request required: false schema: type: string example: openid - name: claims in: query description: Claims to return in the id_token or from the userinfo endpoint required: false schema: type: string example: "{\"id_token\":{\"birthdate\":null}}" - name: state in: query description: Any client state that needs to be passed onto the redirect URI required: false schema: type: string example: random+value - name: prompt in: query description: Specific prompts a user must be presented with required: false schema: type: string enum: - login - consent example: consent - name: code_challenge in: query description: PKCE code challenge required: false schema: type: string example: base64UrlEncoded(sha256(code_verifier)) - name: code_challenge_method in: query description: PKCE code challenge method required: false schema: type: string enum: - S256 example: S256 - name: request_uri in: query description: Obtained from a post to the /oidc/request endpoint as part of a pushed authorization request (PAR). When used, only a client_id parameter should be additionally provided. required: false schema: type: string example: urn:ietf:params:oauth:request_uri:cnEx7B1mkVFXze4BoZWp5 responses: '302': description: Redirection to the login screen or error page content: text/html: schema: type: string example: Redirecting to <a href="/oidc/interaction/c1a95bc5-7f40-4e2e-81d0-2be0b5c56106">/oidc/interaction/c1a95bc5-7f40-4e2e-81d0-2be0b5c56106</a> '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/authBad' '500': description: Internal Server Error post: tags: - Authorization summary: Sends authentication request using a POST request body. description: 'Utilizing a `POST` request, the `/auth` route will redirect to the specified `redirect_uri` with the result of the call found in the URL.' requestBody: content: application/x-www-form-urlencoded: schema: oneOf: - $ref: '#/components/schemas/authRequest' - $ref: '#/components/schemas/parAuthRequest' responses: '302': description: Redirection to the login screen or error page content: text/html: schema: type: string example: Redirecting to <a href="/oidc/interaction/c1a95bc5-7f40-4e2e-81d0-2be0b5c56106">/oidc/interaction/c1a95bc5-7f40-4e2e-81d0-2be0b5c56106</a> '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/authBad' '500': description: Internal Server Error /oidc/request: post: tags: - Authorization summary: Pushed Authorization Request (PAR) description: 'Start an authorization request by posting the payload from one server to the identity provider. Increases security by not exposing the authorization parameters to the user in the brower URL and also supports using unregistered callback URLs.' security: - basicAuth: [] requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authRequest' responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/parResponse' '400': description: Bad Request content: text/html: schema: type: string '500': description: Internal Server Error /oidc/me: get: tags: - User Info summary: Returns info about the authenticated user. description: See the [OpenID Connect Core specs](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). security: - OpenID_Connect: - openid responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userInfo' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/tokenUnauthorized' '500': description: Internal Server Error /oidc/logout: get: tags: - Logout summary: Log a user out and allow custom logout redirects description: | See [OpenID Connect RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). This endpoint is designed to use as a redirect for the end user agent. It will facilitate logging the user out of both the identity provider and relying party sites. parameters: - name: id_token_hint in: query description: | ID Token previously issued. It is passed to the Logout Endpoint as a hint about the End-User's current authenticated session with the Client. Either id_token_hint or client_id must be provided. required: false schema: type: string - name: client_id in: query description: | Client ID of the relying party. It is passed to the Logout Endpoint to enable post_logout_redirect_uri parameters. Either id_token_hint or client_id must be provided. required: false schema: type: string - name: post_logout_redirect_uri in: query description: | URI to which the relying party is requesting that the End-User be redirected after a logout has been performed. This URI SHOULD use the https scheme and MUST be pre-registered as a callback URI for the client. Either a client_id or id_token hint parameter must be passed. required: false schema: type: string - name: state in: query description: Any client state that needs to be passed onto the redirect URI required: false schema: type: string example: random+value responses: '301': description: Redirect the user through a logout flow components: securitySchemes: OpenID_Connect: type: openIdConnect description: OpenID Connect - Discovery endpoint will be institution specific openIdConnectUrl: https://digital.garden-fi.com/a/consumer/api/v0/oidc/.well-known/openid-configuration basicAuth: type: http scheme: basic schemas: certsResponse: type: object properties: keys: type: array items: required: - kid - kty - use type: object properties: kty: type: string example: string kid: type: string example: string use: type: string example: string crv: type: string example: string x: type: string example: string 'y': type: string example: string d: type: string example: string e: type: string example: string 'n': type: string example: string p: type: string example: string q: type: string example: string dp: type: string example: string dq: type: string example: string qi: type: string example: string tokenRequest: required: - client_id - client_secret - grant_type - redirect_uri type: object properties: client_id: type: string example: 0cd6b55a-3017-4e16-aa50-f0cbdb1cd12f client_secret: type: string example: b63f559e-1425-41f9-9381-454b64e1981a grant_type: type: string enum: [authorization_code, refresh_token] example: authorization_code code: type: string description: Authorization code returned from /oidc/auth example: 8xLOxBtZp8 refresh_token: type: string description: Refresh token from a previous token request example: 9yNOxJtZa5 redirect_uri: type: string example: https://example.com/cb code_verifier: type: string description: PKCE code_verifier example: random value tokenRevocationRequest: required: - client_id - client_secret - token type: object properties: client_id: type: string example: 0cd6b55a-3017-4e16-aa50-f0cbdb1cd12f client_secret: type: string example: b63f559e-1425-41f9-9381-454b64e1981a token: type: string description: ID of the token to revoke token_type_hint: type: string example: access_token description: Suggests the type of token passed tokenResponse: required: - access_token - token_type - refresh_token type: object properties: access_token: type: string description: The access token example: TlBN45jURg token_type: type: string description: The type of access token that was given. example: Bearer expires_in: type: string description: The number of seconds the token will take to expire example: '300' refresh_token: type: string description: A refresh token for when the access token is expired. example: 9yNOxJtZa5 id_token: type: string description: Base64-encoded JWT tokenFailure: type: object properties: error: type: string example: Invalid request error_description: type: string example: no client authentication mechanism provided request_id: type: string example: 1658ab6e-9c4c-4f7f-8f7d-991bddccdc90 tokenUnauthorized: type: object properties: error: type: string example: invalid client error_description: type: string example: client authentication failed request_id: type: string example: 1658ab6e-9c4c-4f7f-8f7d-991bddccdc90 authRequest: required: - response_type - client_id type: object properties: response_type: description: The authorization type. Must be set to `code` type: string enum: - code example: code client_id: description: ID of the client type: string example: 00000000-0000-0000-0000-000000000000 redirect_uri: description: The redirect URI as registered by the client. type: string example: https://localhost/cb scope: description: The possible scope of the request type: string example: openid claims: description: Claims to return in the id_token or from the userinfo endpoint type: string example: "{\"id_token\":{\"birthdate\":null}}" state: description: Any client state that needs to be passed onto the redirect URI type: string example: random+value prompt: description: Specific prompts a user must be presented with type: string enum: - login - consent example: consent code_challenge: description: PKCE code challenge type: string example: base64UrlEncoded(sha256(code_verifier)) code_challenge_method: description: PKCE code challenge method - must be `S256` type: string enum: - S256 example: S256 authBad: type: object properties: error: type: string example: invalid_request error_description: type: string example: missing required parameter(s) (client_id) request_id: type: string example: 1658ab6e-9c4c-4f7f-8f7d-991bddccdc90 configResponse: type: object properties: authorization_endpoint: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc/auth claims_parameter_supported: type: boolean example: false claims_supported: type: array items: type: string example: [sub, birthdate, name] grant_types_supported: type: array items: type: string example: [implicit, authorization_code, refresh_token] id_token_signing_alg_values_supported: type: array items: type: string example: [HS256, ES256, RS256, PS256] issuer: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc jwks_uri: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc/jwks request_parameter_supported: type: boolean example: false request_uri_parameter_supported: type: boolean example: false response_modes_supported: type: array items: type: string example: [form_post, fragment, query] response_types_supported: type: array items: type: string example: [code, id_token, none] scopes_supported: type: array items: type: string example: [openid, banno, email, phone] subject_types_supported: type: array items: type: string example: [public] token_endpoint: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc/token token_endpoint_auth_methods_supported: type: array items: type: string example: [none, client_secret_basic] userinfo_endpoint: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc/me userinfo_signing_alg_values_supported: type: array items: type: string example: [HS256, ES256, RS256, PS256] code_challenge_methods_supported: type: array items: type: string example: [S256] revocation_endpoint: type: string example: https://digital.garden-fi.com/a/consumer/api/v0/oidc/token/revocation revocation_endpoint_auth_methods_supported: type: array items: type: string example: [none, client_secret_basic] id_token_encryption_alg_values_supported: type: array items: type: string example: [A256KW, ECDH-ES+A256KW, RSA-OAEP] id_token_encryption_enc_values_supported: type: array items: type: string example: [A256CBC-HS512, A256GCM] userinfo_encryption_alg_values_supported: type: array items: type: string example: [A256KW, ECDH-ES+A256KW, RSA-OAEP] userinfo_encryption_enc_values_supported: type: array items: type: string example: [A256CBC-HS512, A256GCM] claim_types_supported: type: array items: type: string example: [normal] userInfo: type: object properties: sub: type: string description: User ID example: cf857130-6d24-11e9-870c-0242b75cad58 institution_id: type: string example: c8b309b0-fc09-11e5-8adf-0e09432615dc department: type: string nullable: true example: null title: type: string nullable: true example: null family_name: type: string example: Doe given_name: type: string example: John middle_name: type: string nullable: true example: Q name: type: string example: John Doe picture: type: string example: https://banno.com/a/sentry/api/users/cf857130-6d24-11e9-870c-0242b75cad58/profile-image preferred_username: type: string example: jdoe email: type: string example: jdoe@example.com phone_number: type: string example: '"+15555556652"' address: $ref: '#/components/schemas/userAddress' userAddress: type: object properties: locality: type: string example: Cedar Falls postal_code: type: string example: '"506130000"' region: type: string example: IA street_address: type: string example: 2911 Lovejoy Drive parAuthRequest: required: - client_id - request_uri type: object properties: client_id: type: string description: ID of client as given by the authorization server example: string request_uri: type: string example: urn:ietf:params:oauth:request_uri:cnEx7B1mkVFXze4BoZWp5 parResponse: required: - request_uri - expires_in type: object properties: request_uri: type: string description: value to be used as a request_uri parameter in the authorization code flow. example: urn:ietf:params:oauth:request_uri:cnEx7B1mkVFXze4BoZWp5 expires_in: type: number description: duration in seconds during which the request_uri is valid example: 90