OIDC provider (Local development)

The OIDC Provider may be defined to use Maverics as an OIDC IDP.

Supported Grants

The OIDC Provider supports the following grant types:

• authorization_code

• client_credentials

• refresh_token

• password

• implicit

Per OAuth/OIDC security best practices, Strata does NOT recommend using the password grant or implicit grant if other more secure flows are viable. For more info, please reference the password grant's security considerations in RFC 6819 Section 4.4.3 and the implicit grant's security considerations in RFC 7900 Section 2.1.2.

PKCE

The OIDC Provider supports Proof Key for Code Exchange (PKCE) for all OIDC apps using the authorization_code grant type - no additional configuration is required. PKCE is used to mitigate the risk of authorization code interception attacks.

Clients that use PKCE include the code_challenge and code_challenge_method parameters in the authorize request. Currently, the Orchestrator only supports the S256 code challenge method. In the subsequent token request, the client must present the code_verifier which is validated against the original challenge.

PKCE is required for public clients.

Configuration options

Discovery

discovery defines the configuration for OIDC discovery.

Issuer

issuer is the domain to which tokens will be attributed. An issuer is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

The issuer for the OIDC Provider (which is typically obtained during Discovery) will exactly match the value of the iss (issuer) Claim in the ID token.

Endpoints

endpoints defines where the OIDC endpoints are served.

Well-Known
wellKnown is the endpoint where the OIDC Provider will respond metadata requests. This endpoint can be used to discover the endpoints exposed by the server, the scopes available from the server and the algorithms to sign and/or encrypt the access and ID tokens.

This corresponds to OpenID Connect Discovery 1.0, section 3.

JWKS
jwks is the endpoint where the OIDC Provider returns information about the JSON Web Key (JWK) Set it uses to sign JWTs.

This corresponds to RFC 7517: JSON Web Key (JWK).

Authorization
auth is the endpoint where the OIDC Provider will respond to OAuth 2.0 Authorization Request to authenticate the end user.

This corresponds to OpenID Connect Core 1.0, section 3.1.2.

Token
token is the endpoint where the OIDC Provider will respond to the Relying Party with an access token and ID token.

This corresponds to OpenID Connect Core 1.0, section 3.1.3.

Userinfo
userinfo is the endpoint where the OIDC Provider will return claims about the authenticated end user. If available, it will return claims associated with any of the following scopes: profile, openid, phone, email and address.

If claimsMapping has been defined for the corresponding client, those mappings will be applied to the userinfo response.

This corresponds to OpenID Connect Core 1.0, section 5.3.

How scopes relate to claims is defined in OpenID Connect Core 1.0, section 5.4.

Introspect
introspect is the endpoint where the OIDC Provider will return the claims for the access token which is being introspected.

This corresponds to OAuth 2.0 Token Introspection, RFC 7662.

Revoke
revoke is the endpoint where the OIDC Provider will respond to OAuth 2.0 token revocation requests, revoking usage of the specified refresh or access token.

This corresponds to RFC 7009, section 2.

End Session
endSession is the endpoint where the OIDC Provider will respond to RP-initiated logout request.

This corresponds to the OpenID Connect RP-Initiated Logout RFC.

JWKS

jwks is a list of keys used to sign tokens. The key listed first will be used for signing. All public keys will be available for consumption at the JWKS endpoint.

Algorithm

algorithm represents the encryption algorithm that was used to generate the key pair. Currently, only RSA256 is supported.

Private Key

privateKey is the PEM encoded private key. This field can optionally be loaded from a secret provider.

BuildUserInfoClaims Service Extension

buildUserInfoClaimsSE is an optional Service Extension that can customize the claims returned by the userinfo endpoint. The session argument provided in the Service Extension points to session attributes associated with the requested user.

As the author of a Service Extension you are responsible for its behavior, and need ensure that the response adheres to the specification.

Session Correlation

correlateSession is an optional boolean field used to correlate back-channel token requests with the resource owner's session. This correlation allows for tracking an authorization code flow login transaction across both the authorization endpoint and token endpoint. Please note that session ID logging will only occur at the token endpoint when this field is set to true and session ID logging is enabled.

Examples

Basic OIDC Provider Config Example

oidcProvider:
  discovery:
    issuer: https://maverics.sonarsystems.com
    endpoints:
      wellKnown: https://maverics.sonarsystems.com/.well-known/openid-config
      jwks: https://maverics.sonarsystems.com/.well-known/jwks.json
      auth: https://maverics.sonarsystems.com/oauth2/auth
      token: https://maverics.sonarsystems.com/oauth2/token
      userinfo: https://maverics.sonarsystems.com/userinfo
      introspect: https://maverics.sonarsystems.com/introspect
      revoke: https://maverics.sonarsystems.com/revoke
  jwks:
    - algorithm: RSA256
      privateKey: <authorizationServerPrivateKey>
  correlateSession: true

Basic OIDC Provider Config Example With Service Extension

oidcProvider:
  discovery:
    issuer: https://maverics.sonarsystems.com
    endpoints:
      wellKnown: https://maverics.sonarsystems.com/.well-known/openid-config
      jwks: https://maverics.sonarsystems.com/.well-known/jwks.json
      auth: https://maverics.sonarsystems.com/oauth2/auth
      token: https://maverics.sonarsystems.com/oauth2/token
      userinfo: https://maverics.sonarsystems.com/userinfo
      introspect: https://maverics.sonarsystems.com/introspect
      revoke: https://maverics.sonarsystems.com/revoke
      endSession: https://maverics.sonarsystems.com/oidc/logout
  jwks:
    - algorithm: RSA256
      privateKey: <authorizationServerPrivateKey>
  buildUserInfoClaimsSE:
    funcName: BuildUserInfoClaims
    file: /etc/maverics/extensions/auth.go

/etc/maverics/extensions/auth.go

package main

import (
  "net/http"

  "github.com/strata-io/service-extension/orchestrator"
)

func BuildUserInfoClaims(api orchestrator.Orchestrator, _ *http.Request) (map[string]any, error) {
  logger := api.Logger()
  logger.Debug("se", "building user info claims")

  session, err := api.Session()
  if err != nil {
    logger.Error("se", "unable to retrieve session", "error", err.Error())
    return nil, err
  }
  groups, err := session.GetString("okta.groups")
  return map[string]any{
    "groups": groups,
  }, err
}