OpenID API

The OpenID API supports web applications acting as an OpenID Provider (OP), and participating in authentication and logout flows.

For full details of all public APIs, refer to the API reference.

Initialization

The following code adds the OpenID services and specifies the OpenID configuration.

// Add OpenID services.
builder.Services.AddOpenIDProvider(
    builder.Configuration.GetSection("OpenIDProvider"));

Refer to the Configuration section for more options.

IOpenIDProvider

The IOpenIDProvider interface supports OpenID Connect when acting as an OpenID Provider.

Specifying an OpenID Configuration

The ConfigurationName property specifies the OpenID configuration to use.

Setting this property is only required for multi-tenancy support.

Multi-tenancy support refers to a single application accommodating multiple tenants each of whom has their own separate configuration.

For most use cases, a single configuration will suffice, and this property shouldn’t be set.

If there are multiple configurations, this property must be set to the name of the applicable configuration prior to any other OpenID API calls.

string? ConfigurationName { get; set; }

For example:

_openIDProvider.ConfigurationName = configurationName;

Retrieving the OpenID Provider's Metadata

GetMetadataAsync returns the OpenID provider's metadata.

OpenID provider metadata is defined in the OpenID Connect Discovery specification.

GetMetadataAsync may be called to implement the .well-known/openid-configuration endpoint.

Task<IActionResult> GetMetadataAsync ();

For example:

[Route(".well-known/openid-configuration")]
[ResponseCache(Duration = 600, Location = ResponseCacheLocation.Any)]
public async Task<IActionResult> GetMetadataAsync()
{
    // Return the OpenID provider's metadata.
    return await _openIDProvider.GetMetadataAsync();
}

Retrieving the OpenID Provider's Keys

GetKeysAsync returns the OpenID provider's public keys as a JSON Web Key Set document.

GetKeysAsync may be called to implement the jwks_uri endpoint.

Task<IActionResult> GetKeysAsync();

For example:

[Route("openid/keys")]
[ResponseCache(Duration = 600, Location = ResponseCacheLocation.Any)]
public async Task<IActionResult> GetKeysAsync()
{
    // Return the OpenID provider's keys.
    return await _openIDProvider.GetKeysAsync();
}

Receiving an Authentication Request

ReceiveAuthnRequestAsync receives an OpenID Connect authentication request from a client.

The received authentication request is returned.

Task<AuthenticationRequest> ReceiveAuthnRequestAsync();

For example:

var authenticationRequest = await _openIDProvider.ReceiveAuthnRequestAsync();

Sending an Authentication Response

SendAuthnResponseAsync sends an OpenID Connect authentication response to a client.

Task<IActionResult> SendAuthnResponseAsync(
    string subject, 
    IEnumerable<Claim>? claims = null, 
    string? accessToken = null, 
    string? refreshToken = null, 
    DateTime? utcAccessTokenExpiresAt = null, 
    string? correlationID = null);

For example:

await _openIDProvider.SendAuthnResponseAsync(subject, claims, accessToken);

subject

The subject to include in the authentication response.

claims

The claims to include in the authentication response.

accessToken

The access token to include in the authentication response.

refreshToken

The refresh token to include in the authentication response.

utcAccessTokenExpiresAt

The UTC time when the access token expires.

correlationID

The correlation ID identifying the authentication request to respond to.

Sending an Error Authentication Response

SendAuthnErrorResponseAsync sends an OpenID Connect authentication error response to a client.

Task<IActionResult> SendAuthnErrorResponseAsync(
    string errorCode, 
    string? errorDescription = null, 
    string? errorUri = null, 
    string? correlationID = null);

For example:

await _openIDProvider.SendAuthnErrorResponseAsync(
    _openIDProvider.ToErrorCode(exception));

Converting an Exception to an Error Code

ToErrorCode converts an exception into an OpenID error code.

string ToErrorCode(Exception exception);

For example:

var errorCode = _openIDProvider.ToErrorCode(exception);

Retrieving an ID Token

GetTokensAsync returns the ID token to a client as part of the authorization code flow.

Task<IActionResult> GetTokensAsync(
    GetRefreshTokenResultAsync? getRefreshTokenResult = null, 
    GetClientCredentialsResultAsync? getClientCredentialsResult = null,
    GetUserCredentialsResultAsync? getUserCredentialsResult = null);

For example:

await _openIDProvider.GetTokensAsync(
    GetRefreshTokenResultAsync, 
    GetClientCredentialsResultAsync, 
    GetUserCredentialsResultAsync)

getRefreshTokenResult

Delegate that returns the access token, its expiry, and the new refresh token for the refresh_token grant type.

public delegate Task<RefreshTokenResult> GetRefreshTokenResultAsync(
    string clientID, 
    string refreshToken);

getClientCredentialsResult

Delegate that returns the new access token and its expiry for the client_credentials grant type.

public delegate Task<ClientCredentialsResult> GetClientCredentialsResultAsync(
    string clientID, 
    string? scope = null);

getUserCredentialsResult

Delegate that returns the new access token and its expiry for the password (user credentials) grant.

public delegate Task<UserCredentialsResult> GetUserCredentialsResultAsync(
    string clientID, 
    string? userName = null, 
    string? userPassword = null, 
    string? scope = null);

Retrieving the User Information

GetUserInfoAsync returns the user information to a client.

Task<IActionResult> GetUserInfoAsync();

For example:

await _openIDProvider.GetUserInfoAsync();

Introspecting the Token

IntrospectTokenAsync returns information about the access token to a client.

Task<IActionResult> IntrospectTokenAsync();

For example:

await _openIDProvider.IntrospectTokenAsync();

Receiving a Logout Request

ReceiveLogoutRequestAsync receives an OpenID Connect logout request from a client.

The received logout request is returned.

Task<LogoutRequest> ReceiveLogoutRequestAsync();

For example:

var logoutRequest = await _openIDProvider.ReceiveLogoutRequestAsync();

Sending a Logout Response

SendLogoutResponseAsync sends an OpenID Connect logout respnse to a client.

Task<IActionResult> SendLogoutResponseAsync(string? correlationID = null);

For example:

await _openIDProvider.SendLogoutResponseAsync();

correlationID

The correlation ID identifying the logout request to respond to.

Getting the Status

GetStatusAsync returns the OpenID session status.

The returned dictionary's keys are the client ID. The dictionary's values are the corresponding status for that client.

Task<IDictionary<string, IOpenIDStatus>> GetStatusAsync();

For example:

var status = await _openIDProvider.GetStatusAsync();

Creating a JWT Access Token

CreateJwtAccessTokenAsync creates a JWT access token.

Task<string> CreateJwtAccessTokenAsync(
    string clientID, 
    string audience, 
    string? subject = null, 
    string? scope = null, 
    IList<Claim>? claims = null,
    DateTime? utcJwtExpiresAt = null);

For example:

var accessToken = await _openIDProvider.CreateJwtAccessTokenAsync(
    clientID, audience, subject);

clientID

The client ID.

audience

The audience.

subject

The subject.

scope

The scope.

claims

The claims.

utcJwtExpiresAt

The UTC expiry time for the JWT.

Revoking an Access Token

RevokeAccessTokenAsync revokes an access token.

Task RevokeAccessTokenAsync(string accessToken);

For example:

await _openIDProvider.RevokeAccessTokenAsync(accessToken);

accessToken

The access token to be revoked.

Clearing the Session State

ClearSessionAsync clears the OpenID session state.

Task RevokeAccessTokenAsync(string accessToken);

For example:

await _openIDProvider.RevokeAccessTokenAsync(accessToken);