finOidc

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793816181/FIN+5.3.1+finOidc 中文整理基于 FIN 5.3.1

导读： FIN OpenID Connect 单点登录

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

classes
enums
errs
Slot Details
- DEFAULT_EXPIRATION_DURATION
- code
- codeChallenge
- creation
- isExpired
- make
- nonce
- redirectUri
- serverSessionId
- state
- toUri
- user
- add
- cleanup
- get
- isEmpty
- remove
- AUTHORIZATION_CODE
- authEndpoint
- responseType
- scope
- authorize
- clientId
- codeChallengeMethod
- authCode
- authorization
- codeVerifier
- tokens
- verifyAuthorization
- claims
- set
- isEqual
- isEqualStr
- discovery
- handleScheme
- log
- login
- sessionByAuthToken
- userByUsername
- userSecret
- finOidcServerDetails
- FIN_META_PREFIX
- api
- authenticate
- getFinVersion
- lib
- onLogout
- onStart
- settings
- web
- applyTagsFunc
- authOptions
- callbackUrls
- clientSecret
- discoveryEndpointUri
- logoutEndpointUri
- request
- tokenEndpoint

API 正文（英文）

errs


OidcErr	An OpenID Connect error.

AuthCodeInfo

const class AuthCodeInfo : Obj

The authorization code info that's cached in the server once a request is made.

Constructors


make

Fields


DEFAULT_EXPIRATION_DURATION	The default expiration duration.
code	The authorization code.
codeChallenge	The code challenge created when the code was created.
creation	The time when the auth code was created.
nonce	The nonce when the code was created.
redirectUri	The requested redirect URI.
serverSessionId	The id of the web server session.
state	The state associated with the original request.
user	The user associated with the authorization request.

Methods


isExpired	Return true if the auth code is now expired.
toUri	Return the auth code response URI.

Slot Details

DEFAULT_EXPIRATION_DURATION

const static Duration DEFAULT_EXPIRATION_DURATION := 1min

The default expiration duration.

This is intentionally quite short as this should be requested very quickly.

code

const Str code

The authorization code.

codeChallenge

const Str codeChallenge

The code challenge created when the code was created.

creation

const Duration creation

The time when the auth code was created.

isExpired

Bool isExpired()

Return true if the auth code is now expired.

make

new make(Str code, Uri redirectUri, Str codeChallenge, Str nonce, Str state, User user, Str serverSessionId, Duration creation := Duration.now())

nonce

const Str nonce

The nonce when the code was created.

redirectUri

const Uri redirectUri

The requested redirect URI.

serverSessionId

const Str serverSessionId

The id of the web server session.

state

const Str state

The state associated with the original request.

toUri

Uri toUri()

Return the auth code response URI.

user

const User user

The user associated with the authorization request.

AuthCodeStore

const class AuthCodeStore : Obj

Holds auth code information.

Methods


add	Add an auth code to the store.
cleanup	Remove any expired entries from the store.
get	Return the auth code information or null if it can't be found.
isEmpty	Return true if the store is empty.
remove	Remove the auth code from the store.

Slot Details

add

Void add(AuthCodeInfo info)

Add an auth code to the store.

cleanup

Void cleanup()

Remove any expired entries from the store.

get

AuthCodeInfo? get(Str code)

Return the auth code information or null if it can't be found.

isEmpty

Bool isEmpty()

Return true if the store is empty.

remove

Void remove(Str code)

Remove the auth code from the store.

AuthRequest

class AuthRequest : Obj

An OpenId Connect authentication request.

This implementation also protects against authorization code interception attacks by using an additional code challenge (https://datatracker.ietf.org/doc/html/rfc7636).

https://openid.net/specs/openid-connect-core-1\_0.html#AuthRequest

Constructors


make

Fields


AUTHORIZATION_CODE	Used to specify the authorization code grant.
authEndpoint	The authorization endpoint server to send the authorization request to.
clientId	Client identifier value.
codeChallengeMethod	PKCE for code challenge method.
codeVerifier	PKCE for code verifier.
nonce	A value used to mitigate replay attacks.
options	Additional options to be included in the authorization request.
redirectUri	Redirection URI to which the response will be sent.
responseType	Response type value that determines the authorization processing flow to be used.
scope	Required scope value.
state	Opaque value used to maintain state between the request and the callback.

Methods


toUri	Return a URI encoded authorization request.

Slot Details

AUTHORIZATION_CODE

const static Str AUTHORIZATION_CODE := "code"

Used to specify the authorization code grant.

authEndpoint

Uri authEndpoint := ``

The authorization endpoint server to send the authorization request to.

clientId

Str clientId := ""

Client identifier value.

Encoded as <client_id>.

codeChallengeMethod

Str codeChallengeMethod := "S256"

PKCE for code challenge method.

https://datatracker.ietf.org/doc/html/rfc7636

Encoded as <code_challenge_method>.

codeVerifier

Str codeVerifier

PKCE for code verifier.

https://datatracker.ietf.org/doc/html/rfc7636

make

new make()

nonce

Str nonce

A value used to mitigate replay attacks. This value is passed to the identity token accordingly.

https://openid.net/specs/openid-connect-core-1\_0.html#CodeFlowSteps

options

Str:Str options := [Str:Str][:]

Additional options to be included in the authorization request.

redirectUri

Uri redirectUri := ``

Redirection URI to which the response will be sent. This URI must exactly match one of the redirection URIs held by the provider.

Encoded as <redirect_uri>.

responseType

Str responseType := AUTHORIZATION_CODE

Response type value that determines the authorization processing flow to be used.

Encoded as <response_type>.

scope

Str[] scope := Str[,]

Required scope value.

Encoded as scope with the values being space separated.

state

Str state

Opaque value used to maintain state between the request and the callback. Typically, CSRF mitgation is done by cryptographically binding the value of this parameter with a browser cookie.

toUri

Uri toUri()

Return a URI encoded authorization request.

AuthResponse

class AuthResponse : Obj

Provides a response to the authorization request.

https://openid.net/specs/openid-connect-core-1\_0.html#AuthRequest https://openid.net/specs/openid-connect-core-1\_0.html#AuthRequestValidation

Constructors


make

Fields


clientId	Client identifier value.
codeChallenge	PKCE code challenge.
codeChallengeMethod	PKCE code challenge method.
nonce	A value used to mitigate replay attacks.
redirectUri	Redirection URI to which the response will be sent.
responseType	Response type value that determines the authorization processing flow to be used.
scope	Required scope value.
state	Opaque value used to maintain state between the request and the callback.

Methods


authorize	Authorize the request and return a URI for the client to redirect too.

Slot Details

authorize

AuthCodeInfo authorize()

Authorize the request and return a URI for the client to redirect too.

Throws an OidcErr if the authorization is invalid.

clientId

Str? clientId

Client identifier value.

codeChallenge

Str? codeChallenge

PKCE code challenge.

https://datatracker.ietf.org/doc/html/rfc7636

codeChallengeMethod

Str? codeChallengeMethod

PKCE code challenge method.

https://datatracker.ietf.org/doc/html/rfc7636

make

new make(Str serverClientId, User user, Str serverSessionId, |Uri->Bool| redirectUriValidator)

nonce

Str? nonce

A value used to mitigate replay attacks. This value is passed to the identity token accordingly.

https://openid.net/specs/openid-connect-core-1\_0.html#CodeFlowSteps

redirectUri

Str? redirectUri

Redirection URI to which the response will be sent. This URI must exactly match one of the redirection URIs held by the provider.

responseType

Str? responseType

Response type value that determines the authorization processing flow to be used.

scope

Str? scope

Required scope value.

state

Str? state

Opaque value used to maintain state between the request and the callback. Typically, CSRF mitgation is done by cryptographically binding the value of this parameter with a browser cookie.

AuthTokenResponse

class AuthTokenResponse : Obj

Provides a response for creating tokens using the authorization code grant type.

https://openid.net/specs/openid-connect-core-1\_0.html#TokenRequest

Constructors


make

Fields


authCode	The authorization code information.
authorization	The authorization header value.
clientId	The client identifier value.
code	The authorization code to use.
codeVerifier	PKCE for code verifier.
redirectUri	The redirection URI.

Methods


tokens	Return the authorization tokens or throw a token error.
verifyAuthorization

Slot Details

authCode

AuthCodeInfo? authCode

The authorization code information.

authorization

Str? authorization

The authorization header value.

clientId

Str? clientId

The client identifier value.

code

Str? code

The authorization code to use.

codeVerifier

Str? codeVerifier

PKCE for code verifier.

https://datatracker.ietf.org/doc/html/rfc7636

make

new make(Str serverClientId, Str serverClientSecret, TokenSessionStore tokenSessions, Uri hostUri)

redirectUri

Str? redirectUri

The redirection URI.

tokens

OidcTokens tokens()

Return the authorization tokens or throw a token error.

https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4

verifyAuthorization

static Void verifyAuthorization(Str serverClientId, Str serverClientSecret, TokenSessionStore tokenSessions, Str? authorization)

ClientStateInfo

const class ClientStateInfo : Obj

Holds state information between network requests.

Constructors


make

Fields


DEFAULT_EXPIRATION_DURATION	The default expiration duration.
claims	User claims from the identity token.
codeVerifier	The code verification code.
nonce	Nonce associated with the authentication request that should also be in the identity token.
redirectUri	The URI to redirect to after the user has logged in.

Methods


isExpired	Return true if the entry has expired.

Slot Details

DEFAULT_EXPIRATION_DURATION

const static Duration DEFAULT_EXPIRATION_DURATION := 1hr

The default expiration duration.

claims

const Str:Obj claims

User claims from the identity token.

codeVerifier

const Str codeVerifier

The code verification code.

isExpired

Bool isExpired()

Return true if the entry has expired.

make

new make(Str codeVerifier, Uri redirectUri, Str:Obj claims, Str nonce, Duration creation := Duration.now())

nonce

const Str nonce

Nonce associated with the authentication request that should also be in the identity token.

redirectUri

const Uri redirectUri

The URI to redirect to after the user has logged in.

ClientStateStore

const class ClientStateStore : Obj

Holds state information.

Methods


cleanup	Remove any expired entries from the store.
get	Return the state information or null if it can't be found.
isEmpty	Return true if the store is empty.
remove	Remove the state information from the store.
set	Add the state to the store.

Slot Details

cleanup

Void cleanup()

Remove any expired entries from the store.

get

ClientStateInfo? get(Str state)

Return the state information or null if it can't be found.

isEmpty

Bool isEmpty()

Return true if the store is empty.

remove

Void remove(Str state)

Remove the state information from the store.

set

Void set(Str state, ClientStateInfo stateInfo)

Add the state to the store.

ConstantTime

class ConstantTime : Obj

A utility class for constant time value comparisons.

These equality methods are used to prevent timing attacks.

https://owasp.org/www-pdf-archive/2018-02-05-AhmadAshraff.pdf

Methods


isEqual	Returns true if the buffers are equal.
isEqualStr	Returns true if the two strings are equal.

Slot Details

isEqual

static Bool isEqual(Buf a, Buf b)

Returns true if the buffers are equal.

The comparison uses a constant amount of time.

isEqualStr

static Bool isEqualStr(Str a, Str b)

Returns true if the two strings are equal.

The comparison uses a constant amount of time.

DiscoveryRequest

const class DiscoveryRequest : Obj

Requests all the look up discovery information.

Constructors


make

Methods


get	Return the entry in the discovery parameters or null if not found.

Slot Details

get

Str? get(Str id)

Return the entry in the discovery parameters or null if not found.

make

new make(FinOidcMod mod)

DiscoveryResponse

const class DiscoveryResponse : Obj

Creates a discovery response.

https://openid.net/specs/openid-connect-discovery-1\_0.html

Constructors


make

Methods


discovery	Returns a new discovery response object.

Slot Details

discovery

Str:Obj discovery()

Returns a new discovery response object.

make

new make(Uri hostUri)

FinAuthServerContext

class FinAuthServerContext : AuthServerContext

Handles SCRAM based authentication when responding with tokens in FIN to FIN use case.

This was added as an extra security enhancement on top of the OpenID Connect specification for the FIN to FIN use case where by default everything is encrypted but necessarily trusted due to the likelyhood of self-signed certificates.

Constructors


make

Fields


log

Methods


handleScheme
login
sessionByAuthToken
userByUsername
userSecret

Slot Details

handleScheme

protected virtual override AuthMsg? handleScheme(Str schemeName, AuthMsg reqMsg)

log

virtual override Log log

virtual override Str login()

make

new make(Str clientId, Str clientSecret, TokenSessionStore tokenSessions, Log log)

sessionByAuthToken

virtual override Obj? sessionByAuthToken(Str authToken)

userByUsername

virtual override AuthUser? userByUsername(Str username)

userSecret

virtual override Str? userSecret()

FinOidcLib

const class FinOidcLib : Obj

Axon functions for FIN OIDC

Constructors


make

Methods


finOidcServerDetails

Slot Details

finOidcServerDetails

@Axon { su=true; meta=... } Grid finOidcServerDetails()

make

new make(FinOidcMod mod)

FinOidcMod

const class FinOidcMod : AuthPluginMod

FIN OpenID Connect SysMod.

A SysMod that uses OpenID Connect with FIN.

Fields


FIN_META_PREFIX	Prefix used on all encoded user FIN meta claims.
api	Required to register the sys mod dynamically in the fin boot environment.
lib	Axon functions.
web	Special web service handling.

Methods


authenticate	The main authentication hook for OpenID Connect.
getFinVersion	Return the version of FIN being used.
onLogout
onStart
settings	Settings for OpenID Connect.

Slot Details

FIN_META_PREFIX

const static Str FIN_META_PREFIX := "fin:meta:"

Prefix used on all encoded user FIN meta claims.

api

const static Str api := FinOidcMod#.pod().name

Required to register the sys mod dynamically in the fin boot environment. This is detected via reflection.

authenticate

virtual override WebServerSession? authenticate(AuthContext cx)

The main authentication hook for OpenID Connect.

This method starts the following process...

Redirect the user to the authorization server to log in.
Once authenticated, the authorization server redirects back to this host with an authorization code.
See FinOidcWeb#handleAuthResponseRedirect for the redirect handling.
This host uses the authorization code to get the identity, access and refresh tokens.
This host creates the web session and redirects the user to their original intended page.

getFinVersion

static Str getFinVersion()

Return the version of FIN being used.

lib

const FinOidcLib lib := FinOidcLib.<ctor>(this)

Axon functions.

onLogout

virtual override Void onLogout(AuthContext cx, User user)

onStart

virtual override Void onStart()

settings

virtual override FinOidcSettings settings()

Settings for OpenID Connect.

web

virtual const override FinOidcWeb web := FinOidcWeb.<ctor>(this)

Special web service handling.

FinOidcSettings

const class FinOidcSettings : Settings

Settings for FIN OpenID Connect.

Currently edited via <var/host/folio.trio>. See id:@finOidc.

Constructors


make

Fields


applyTagsFunc	Axon callback function used to set/change tags on a user before a session is created.
authOptions	A comma separated list of extra options to include in the authorization request.
callbackUrls	A comma separated list of callback URIs used by the server.
clientId	The OpenID Connect client id.
discoveryEndpointUri	The OpenID Connect discovery endpoint.
hostUri	This host's URI.
logoutEndpointUri	The OpenID Connect logout endpoint.
logoutMethod	The logout HTTP method to use.
scope	A comma separate list of scopes to use.
serverEnabled	Indicates whether the OIDC server is enabled.
serverHttpsOnly	Force HTTPS only.
userProtoAttr	The claim to check in the user's identity token for mapping to a user prototype (group).
userProtoDefault	Optional fallback user prototype (group) if a user prototype (group) cannot be found.
userProtoPriority	If a user maps to multiple user prototypes (groups), this list specifies the priority of which one should be chosen.

Methods


clientSecret	Return the client secret to use.
toAuthOptions	Returns the authorization options.
toHostUri	Return the host URI to use.
toScope	Return the scope setting as a list.

Slot Details

applyTagsFunc

@Setting { meta="multiLine" } const Str applyTagsFunc := ""

Axon callback function used to set/change tags on a user before a session is created. The function should take two parameters (user, attrs) where user is the current User tags (with prototype (group)) already applied) and claims are from the user's identity token. Returns the updated user dict.

(user, claims) => do
 user = user.set("email", claims["custom:email"])
end

authOptions

@Setting const Str authOptions := ""

A comma separated list of extra options to include in the authorization request.

For example... access_type=offline,another_option=foo

callbackUrls

@Setting const Str callbackUrls := "*"

A comma separated list of callback URIs used by the server.

An asterisk means any callback URL is accepted (as long as the client id and secret is valid).

clientId

@Setting const Str clientId := ""

The OpenID Connect client id.

https://openid.net/specs/openid-connect-core-1\_0.html#CodeFlowAuth

clientSecret

Str clientSecret(Sys sys)

Return the client secret to use.

This is always stored as an encrypted password within the settings framework.

discoveryEndpointUri

@Setting

const Uri discoveryEndpointUri := `` ```

The OpenID Connect discovery endpoint.

https://openid.net/specs/openid-connect-discovery-1\_0.html

---

 

### hostUri

``` @Setting  
const Uri hostUri := `` ```

This host's URI.

---

 

### logoutEndpointUri

``` @Setting  
const Uri logoutEndpointUri := `` ```

The OpenID Connect logout endpoint.

---

 

### logoutMethod

`@Setting  
const Str logoutMethod := "GET"`

The logout HTTP method to use.

---

 

### make

`new make(|This| f)`

---

 

### scope

`@Setting  
const Str scope := "openid, email, profile"`

A comma separate list of scopes to use.

---

 

### serverEnabled

`@Setting  
const Bool serverEnabled := false`

Indicates whether the OIDC server is enabled.

---

 

### serverHttpsOnly

`@Setting  
const Bool serverHttpsOnly := true`

Force HTTPS only.

If set to false, HTTP will also be allowed.

---

 

### toAuthOptions

`Str:Str toAuthOptions()`

Returns the authorization options.

---

 

### toHostUri

`Uri toHostUri(Sys sys)`

Return the host URI to use.

---

 

### toScope

`Str[] toScope()`

Return the scope setting as a list.

---

 

### userProtoAttr

`@Setting  
const Str userProtoAttr := ""`

The claim to check in the user's identity token for mapping to a user prototype (group).

---

 

### userProtoDefault

`@Setting  
const Str userProtoDefault := ""`

Optional fallback user prototype (group) if a user prototype (group) cannot be found.

---

 

### userProtoPriority

`@Setting  
const Str userProtoPriority := ""`

If a user maps to multiple user prototypes (groups), this list specifies the priority of which one should be chosen.

 

---

 

# FinOidcWeb

`const class FinOidcWeb : SysWeb`

Web request handling.

Handles all paths from </finOidc>.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [client](#client) | The client web mod. |
| [server](#server) | The server web mod. |

 

**Methods**

|  |  |
| --- | --- |
| [onService](#onService) |  |

## Slot Details

---

 

### client

`const FinOidcWebClient client`

The client web mod.

---

 

### make

`new make(FinOidcMod mod)`

---

 

### onService

`virtual override Void onService()`

---

 

### server

`const FinOidcWebServer server`

The server web mod.

 

---

 

# FinOidcWebClient

`const class FinOidcWebClient : WebMod`

Web request handling for the OpenID Connect client implementation.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [OIDC\_STATE\_COOKIE\_NAME](#OIDC_STATE_COOKIE_NAME) | The name given to the cookie used to store the OpenId connect state. |
| [OIDC\_TOKENS](#OIDC_TOKENS) | The name of the key used to look up the OIDC tokens in the web session. |
| [discovery](#discovery) | The discovery parameters. |
| [stateStore](#stateStore) | Used to tracking state. |

 

**Methods**

|  |  |
| --- | --- |
| [getRedirectUri](#getRedirectUri) |  |
| [isEnabled](#isEnabled) | Return true if the client is enabled. |
| [logout](#logout) | Log the user out from the remote authorization server. |
| [onGet](#onGet) |  |
| [onPost](#onPost) |  |

## Slot Details

---

 

### OIDC\_STATE\_COOKIE\_NAME

`const static Str OIDC_STATE_COOKIE_NAME := "oidc-state"`

The name given to the cookie used to store the OpenId connect state.

---

 

### OIDC\_TOKENS

`const static Str OIDC_TOKENS := "oidc-tokens"`

The name of the key used to look up the OIDC tokens in the web session.

---

 

### discovery

`const DiscoveryRequest discovery`

The discovery parameters.

---

 

### getRedirectUri

`Uri getRedirectUri()`

---

 

### isEnabled

`Bool isEnabled()`

Return true if the client is enabled.

---

 

### logout

`Void logout(WebRes res)`

Log the user out from the remote authorization server.

---

 

### make

`new make(FinOidcMod mod)`

---

 

### onGet

`virtual override Void onGet()`

---

 

### onPost

`virtual override Void onPost()`

---

 

### stateStore

`const ClientStateStore stateStore := ClientStateStore.<ctor>()`

Used to tracking state.

 

---

 

# FinOidcWebServer

`const class FinOidcWebServer : WebMod`

Web request handling for the OpenID Connect server implementation.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Methods**

|  |  |
| --- | --- |
| [onGet](#onGet) |  |
| [onPost](#onPost) |  |
| [start](#start) | Called when the underlying SysMod is started |

## Slot Details

---

 

### make

`new make(FinOidcMod mod)`

---

 

### onGet

`virtual override Void onGet()`

---

 

### onPost

`virtual override Void onPost()`

---

 

### start

`Void start()`

Called when the underlying SysMod is started

 

---

 

# IdTokenFactory

`class IdTokenFactory : Obj`

Makes a new id token.

 

**Fields**

|  |  |
| --- | --- |
| [DEFAULT\_EXPIRATION\_TIME](#DEFAULT_EXPIRATION_TIME) | The default expiration time for the access token. |
| [TAGS\_TO\_SKIP](#TAGS_TO_SKIP) | Always skip copying these tags over. |

 

**Methods**

|  |  |
| --- | --- |
| [makeIdToken](#makeIdToken) | Return a new digitally signed identity token. |
| [makeUserInfo](#makeUserInfo) | Returnt the user info for the user. |

## Slot Details

---

 

### DEFAULT\_EXPIRATION\_TIME

`const static Duration DEFAULT_EXPIRATION_TIME := 1hr`

The default expiration time for the access token.

---

 

### TAGS\_TO\_SKIP

`const static Str[] TAGS_TO_SKIP := Str["userPasswordReset","eula"]`

Always skip copying these tags over.

---

 

### makeIdToken

`static Str makeIdToken(User user, Uri hostUri, Str clientId, Str nonce)`

Return a new digitally signed identity token.

https://openid.net/specs/openid-connect-core-1\_0.html#CodeIDToken

---

 

### makeUserInfo

`static Str:Obj makeUserInfo(User user)`

Returnt the user info for the user.

 

---

 

# IdentityTokenValidator

`class IdentityTokenValidator : Obj`

Validates a JWT identity token.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [claims](#claims) |  |
| [header](#file-IdentityTokenValidator) |  |

 

**Methods**

|  |  |
| --- | --- |
| [validate](#validate) | Validate the identity token and throw an error if there's a problem. |

## Slot Details

---

 

### claims

`const Str:Obj claims`

---

 

### header

`const Str:Str header`

---

 

### make

`new make(Str identityToken, Uri issuer, Str clientId, Str nonce, |Str->[Str:Str]?| getJwk, DateTime now := DateTime.now())`

---

 

### validate

`IdentityTokenValidator validate()`

Validate the identity token and throw an error if there's a problem.

https://openid.net/specs/openid-connect-core-1\_0.html#IDTokenValidation

 

---

 

# JwksRequest

`const class JwksRequest : Obj`

Requests JSON Web Keys.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Methods**

|  |  |
| --- | --- |
| [getJwk](#getJwk) | Return the JSON web key for the key id or null if it can't be found. |

## Slot Details

---

 

### getJwk

`[Str:Str]? getJwk(Str kid)`

Return the JSON web key for the key id or null if it can't be found.

---

 

### make

`new make(DiscoveryRequest discovery)`

 

---

 

# OidcErr

`const class OidcErr : Err`

An OpenID Connect error.

https://openid.net/specs/openid-connect-core-1\_0.html#OidcError https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [INVALID\_CLIENT](#INVALID_CLIENT) | Not found or invalid client. |
| [INVALID\_GRANT](#INVALID_GRANT) | The provided authorization grant is invalid. |
| [INVALID\_REQUEST](#INVALID_REQUEST) | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
| [INVALID\_REQUEST\_URI](#INVALID_REQUEST_URI) | The request\_uri in the Authorization Request returns an error or contains invalid data. |
| [INVALID\_SCOPE](#INVALID_SCOPE) | The requested scope is invalid, unknown, or malformed. |
| [INVALID\_TOKEN](#INVALID_TOKEN) | The token is invalid or does not exist. |
| [UNAUTHORIZED\_CLIENT](#UNAUTHORIZED_CLIENT) | The client is not authorized to request an authorization code using this method. |
| [UNSUPPORTED\_RESPONSE\_TYPE](#UNSUPPORTED_RESPONSE_TYPE) | The authorization server does not support obtaining an authorization code using this method. |
| [description](#description) |  |
| [error](#error) |  |
| [state](#state) |  |

 

**Methods**

|  |  |
| --- | --- |
| [fromUri](#fromUri) | Create an error from a URI. |
| [toJson](#toJson) | Create an token error from a URI. |
| [toUri](#toUri) | Convert into an error URI. |

## Slot Details

---

 

### INVALID\_CLIENT

`const static Str INVALID_CLIENT := "invalid_client"`

Not found or invalid client.

---

 

### INVALID\_GRANT

`const static Str INVALID_GRANT := "invalid_grant"`

The provided authorization grant is invalid.

---

 

### INVALID\_REQUEST

`const static Str INVALID_REQUEST := "invalid_request"`

The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

---

 

### INVALID\_REQUEST\_URI

`const static Str INVALID_REQUEST_URI := "invalid_request_uri"`

The request\_uri in the Authorization Request returns an error or contains invalid data.

---

 

### INVALID\_SCOPE

`const static Str INVALID_SCOPE := "invalid_scope"`

The requested scope is invalid, unknown, or malformed.

---

 

### INVALID\_TOKEN

`const static Str INVALID_TOKEN := "invalid_token"`

The token is invalid or does not exist.

---

 

### UNAUTHORIZED\_CLIENT

`const static Str UNAUTHORIZED_CLIENT := "unauthorized_client"`

The client is not authorized to request an authorization code using this method.

---

 

### UNSUPPORTED\_RESPONSE\_TYPE

`const static Str UNSUPPORTED_RESPONSE_TYPE := "unsupported_response_type"`

The authorization server does not support obtaining an authorization code using this method.

---

 

### description

`const Str description`

---

 

### error

`const Str error`

---

 

### fromUri

`static OidcErr fromUri(Uri uri)`

Create an error from a URI.

---

 

### make

`new make(Str error, Str description, Str? state := null)`

---

 

### state

`const Str? state`

---

 

### toJson

`Str:Str toJson()`

Create an token error from a URI.

---

 

### toUri

`Uri toUri(Uri hostUri)`

Convert into an error URI.

 

---

 

# OidcTokens

`const class OidcTokens : Obj`

OIDC access, refresh and id tokens.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [ACCESS\_TOKEN](#ACCESS_TOKEN) | The JSON key for the access token. |
| [EXPIRES\_IN](#EXPIRES_IN) | The JSON key for expires in. |
| [ID\_TOKEN](#ID_TOKEN) | The JSON key for the id token. |
| [REFRESH\_TOKEN](#REFRESH_TOKEN) | The JSON key for the refresh token. |
| [access](#access) | The OAuth2 access token. |
| [creation](#creation) |  |
| [expiresIn](#expiresIn) | The expiration time. |
| [id](#id) | The OIDC identity token. |
| [nonce](#nonce) | Server side only - The nonce used when authorization was requested. |
| [refresh](#refresh) | The OAuth2 refresh token (used to refresh the access token once it's expired). |
| [serverSessionId](#serverSessionId) | Server side only - the server session id. |
| [user](#user) | Server side only - The associated user. |

 

**Methods**

|  |  |
| --- | --- |
| [isExpired](#isExpired) | Return true if the access token has expired. |
| [toJson](#toJson) | Return the tokens as a JSON object. |

## Slot Details

---

 

### ACCESS\_TOKEN

`const static Str ACCESS_TOKEN := "access_token"`

The JSON key for the access token.

---

 

### EXPIRES\_IN

`const static Str EXPIRES_IN := "expires_in"`

The JSON key for expires in.

---

 

### ID\_TOKEN

`const static Str ID_TOKEN := "id_token"`

The JSON key for the id token.

---

 

### REFRESH\_TOKEN

`const static Str REFRESH_TOKEN := "refresh_token"`

The JSON key for the refresh token.

---

 

### access

`const Str access`

The OAuth2 access token.

---

 

### creation

`const Duration creation`

---

 

### expiresIn

`const Duration expiresIn`

The expiration time.

---

 

### id

`const Str id`

The OIDC identity token.

---

 

### isExpired

`Bool isExpired()`

Return true if the access token has expired.

---

 

### make

`new make(Str access, Str refresh, Str id, Duration expiresIn, Str? serverSessionId := "", User? user := null, Str? nonce := null, Duration creation := Duration.now())`

---

 

### nonce

`const Str? nonce`

Server side only - The nonce used when authorization was requested.

---

 

### refresh

`const Str refresh`

The OAuth2 refresh token (used to refresh the access token once it's expired).

---

 

### serverSessionId

`const Str? serverSessionId`

Server side only - the server session id.

---

 

### toJson

`Str:Obj toJson()`

Return the tokens as a JSON object.

---

 

### user

`const User? user`

Server side only - The associated user.

 

---

 

# OidcTokensStore

`const class OidcTokensStore : Obj`

Holds OIDC tokens.

 

**Methods**

|  |  |
| --- | --- |
| [add](#add) | Add an auth code to the store. |
| [cleanup](#cleanup) | Remove any entries from the store that are no longer valid. |
| [findFromAccessToken](#findFromAccessToken) | Return the tokens that have the matching valid access token. |
| [get](#get) | Return the tokens or null if it can't be found. |
| [isEmpty](#isEmpty) | Return true if the store is empty. |

## Slot Details

---

 

### add

`Void add(OidcTokens tokens)`

Add an auth code to the store.

---

 

### cleanup

`Void cleanup(|Str->Bool| isValid)`

Remove any entries from the store that are no longer valid.

---

 

### findFromAccessToken

`OidcTokens? findFromAccessToken(Str access)`

Return the tokens that have the matching valid access token.

---

 

### get

`OidcTokens? get(Str refresh)`

Return the tokens or null if it can't be found.

---

 

### isEmpty

`Bool isEmpty()`

Return true if the store is empty.

 

---

 

# RefreshTokenResponse

`class RefreshTokenResponse : Obj`

Provides a response for creating tokens using the resfresh token grant type.

https://datatracker.ietf.org/doc/html/rfc6749#section-6

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [authorization](#authorization) | The authorization header value. |
| [oidcTokens](#oidcTokens) | The OIDC tokens |
| [scope](#scope) | The requested scope. |

 

**Methods**

|  |  |
| --- | --- |
| [tokens](#tokens) | Return the authorization tokens or throw a token error. |

## Slot Details

---

 

### authorization

`Str? authorization`

The authorization header value.

---

 

### make

`new make(Str serverClientId, Str serverClientSecret, TokenSessionStore tokenSessions, Uri hostUri, Str serverScope)`

---

 

### oidcTokens

`OidcTokens? oidcTokens`

The OIDC tokens

---

 

### scope

`Str? scope`

The requested scope.

---

 

### tokens

`OidcTokens tokens()`

Return the authorization tokens or throw a token error.

https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4

 

---

 

# TokenRequest

`class TokenRequest : Obj`

An OpenId Connect token request.

This request is made to the authorization server with an authorization code obtained from the authorization request.

https://openid.net/specs/openid-connect-core-1\_0.html#TokenRequest

 

**Fields**

|  |  |
| --- | --- |
| [clientId](#clientId) | The client id. |
| [clientSecret](#clientSecret) | The client secret. |
| [code](#file-TokenRequest) | The authorization code to use. |
| [codeVerifier](#codeVerifier) | PKCE for code verifier. |
| [log](#log) | The log to use for any HTTP requests. |
| [redirectUri](#redirectUri) | The redirection URI. |
| [tokenEndpoint](#tokenEndpoint) | The token endpoint to send the request to. |

 

**Methods**

|  |  |
| --- | --- |
| [params](#params) |  |
| [request](#request) |  |

## Slot Details

---

 

### clientId

`Str clientId := ""`

The client id.

---

 

### clientSecret

`Str clientSecret := ""`

The client secret.

---

 

### code

`Str code := ""`

The authorization code to use.

---

 

### codeVerifier

`Str codeVerifier := ""`

PKCE for code verifier.

https://datatracker.ietf.org/doc/html/rfc7636

---

 

### log

`Log? log`

The log to use for any HTTP requests.

---

 

### params

`Str:Str params()`

---

 

### redirectUri

``` Uri redirectUri := `` ```

The redirection URI.

---

 

### request

`Str:Str request()`

---

 

### tokenEndpoint

``` Uri tokenEndpoint := `` ```

The token endpoint to send the request to.

 

---

 

# TokenSession

`const class TokenSession : Obj`

A temporary token session.

Only used when SCRAM based authorization is used.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [DEFAULT\_EXPIRATION\_DURATION](#DEFAULT_EXPIRATION_DURATION) | The default expiration duration. |
| [creation](#creation) | The time when the token session was created. |
| [id](#id) | A random id used for the token session. |

 

**Methods**

|  |  |
| --- | --- |
| [isExpired](#isExpired) | Return true if the token session is now expired. |

## Slot Details

---

 

### DEFAULT\_EXPIRATION\_DURATION

`const static Duration DEFAULT_EXPIRATION_DURATION := 1min`

The default expiration duration.

This is intentionally quite short as this should be requested very quickly.

---

 

### creation

`const Duration creation`

The time when the token session was created.

---

 

### id

`const Str id := Crypto.random`

A random id used for the token session.

---

 

### isExpired

`Bool isExpired()`

Return true if the token session is now expired.

---

 

### make

`new make(Duration creation := Duration.now())`

 

---

 

# TokenSessionStore

`const class TokenSessionStore : Obj`

Holds token session information.

Only used when SCRAM based authorization is used.

 

**Methods**

|  |  |
| --- | --- |
| [add](#add) | Add a token session to the store. |
| [cleanup](#cleanup) | Remove any expired entries from the store. |
| [get](#get) | Return the token session or null if it can't be found. |
| [isEmpty](#isEmpty) | Return true if the store is empty. |
| [remove](#remove) | Remove the token session from the store. |

## Slot Details

---

 

### add

`Void add(TokenSession session)`

Add a token session to the store.

---

 

### cleanup

`Void cleanup()`

Remove any expired entries from the store.

---

 

### get

`TokenSession? get(Str id)`

Return the token session or null if it can't be found.

---

 

### isEmpty

`Bool isEmpty()`

Return true if the store is empty.

---

 

### remove

`Void remove(Str id)`

Remove the token session from the store.

 

---

 

# UserFactory

`class UserFactory : Obj`

A factory for creating users.

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Methods**

|  |  |
| --- | --- |
| [makeUser](#makeUser) | Returns a new user based on the state information and authorization context. |

## Slot Details

---

 

### make

`new make(Str:Obj claims, Sys sys, Str userProtoAttr, Str userProtoPriority, Str userProtoDefault, Str applyTagsFunc)`

---

 

### makeUser

`UserResult? makeUser()`

Returns a new user based on the state information and authorization context.

 

---

 

# UserInfoResponse

`class UserInfoResponse : Obj`

Provides a response to the userinfo request.

https://openid.net/specs/openid-connect-core-1\_0.html#UserInfo

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [authorization](#authorization) | The authorization header value. |

 

**Methods**

|  |  |
| --- | --- |
| [userInfo](#userInfo) | Returns the user information. |

## Slot Details

---

 

### authorization

`Str? authorization`

The authorization header value.

---

 

### make

`new make(OidcTokensStore oidcTokensStore)`

---

 

### userInfo

`Str:Obj userInfo()`

Returns the user information.

 

---

 

# UserResult

`const class UserResult : Obj`

User factory result

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [userDict](#userDict) |  |
| [userProtoName](#userProtoName) |  |

## Slot Details

---

 

### make

`new make(Dict userDict, Str? userProtoName)`

---

 

### userDict

`const Dict userDict`

---

 

### userProtoName

`const Str? userProtoName`

 

---

 

# UserRole

`@Serializable { simple=true }  
enum class UserRole : Enum`

A user's roles.

 

**Enum**

|  |  |
| --- | --- |
| [su](#su) |  |
| [admin](#admin) |  |
| [op](#op) |  |

 

**Constructors**

|  |  |
| --- | --- |
| [fromStr](#fromStr) | Return the UserRole instance for the specified name. |

 

**Fields**

|  |  |
| --- | --- |
| [vals](#vals) | List of UserRole values indexed by ordinal |

## Slot Details

---

 

### admin

`const static UserRole admin := ...`

---

 

### fromStr

`static new fromStr(Str name, Bool checked := true)`

Return the UserRole instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

---

 

### op

`const static UserRole op := ...`

---

 

### su

`const static UserRole su := ...`

---

 

### vals

`const static UserRole[] vals := ...`

List of UserRole values indexed by ordinal

finOidc ​

目录（导读） ​

API 正文（英文） ​

errs ​

AuthCodeInfo ​

Slot Details ​

DEFAULT_EXPIRATION_DURATION ​

code ​

codeChallenge ​

creation ​

isExpired ​

make ​

nonce ​

redirectUri ​

serverSessionId ​

state ​

toUri ​

user ​

AuthCodeStore ​

Slot Details ​

add ​

cleanup ​

get ​

isEmpty ​

remove ​

AuthRequest ​

Slot Details ​

AUTHORIZATION_CODE ​

authEndpoint ​

clientId ​

codeChallengeMethod ​

codeVerifier ​

make ​

nonce ​

options ​

redirectUri ​

responseType ​

scope ​

state ​

toUri ​

AuthResponse ​

Slot Details ​

authorize ​

clientId ​

codeChallenge ​

codeChallengeMethod ​

make ​

nonce ​

redirectUri ​

responseType ​

scope ​

state ​

AuthTokenResponse ​

Slot Details ​

authCode ​

authorization ​

clientId ​

code ​

codeVerifier ​

make ​

redirectUri ​

tokens ​

verifyAuthorization ​

ClientStateInfo ​

Slot Details ​

DEFAULT_EXPIRATION_DURATION ​

claims ​

codeVerifier ​

isExpired ​

make ​

nonce ​

redirectUri ​

ClientStateStore ​

Slot Details ​

cleanup ​

get ​

isEmpty ​

remove ​

set ​

ConstantTime ​

finOidc

目录（导读）

API 正文（英文）

errs

AuthCodeInfo

Slot Details

DEFAULT_EXPIRATION_DURATION

code

codeChallenge

creation

isExpired

make

nonce

redirectUri

serverSessionId

state

toUri

user

AuthCodeStore

Slot Details

add

cleanup

get

isEmpty

remove

AuthRequest

Slot Details

AUTHORIZATION_CODE

authEndpoint

clientId

codeChallengeMethod

codeVerifier

make

nonce

options

redirectUri

responseType

scope

state

toUri

AuthResponse

Slot Details

authorize

clientId

codeChallenge

codeChallengeMethod

make

nonce

redirectUri

responseType

scope

state

AuthTokenResponse

Slot Details

authCode

authorization

clientId

code

codeVerifier

make

redirectUri

tokens

verifyAuthorization

ClientStateInfo

Slot Details

DEFAULT_EXPIRATION_DURATION

claims

codeVerifier

isExpired

make

nonce

redirectUri

ClientStateStore

Slot Details

cleanup

get

isEmpty

remove

set

ConstantTime