Details
Consumer API
>
API Reference
>
v0
>
OAuth and OpenID Connect
>
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
Have a Question?
- Have a how-to question? Seeing a weird error? Get help on StackOverflow.
- Register for the Developer Office Hours where we answer technical Q&A from the audience.
Did this page help you?
Why was this page helpful?
Why wasn't this page helpful?
Thank you for your feedback!
Last updated Wed May 5 2021