Class OpenBiApiClientAuthExtensions

Namespace

BiExcellence.OpenBi.Api.Auth

Assembly

BiExcellence.OpenBi.Api.Client.dll

Authentication for IOpenBiApiClient, backed by the REST API's OAuth2 /oauth/token endpoint. Call one of LoginAsync(IOpenBiApiClient, string, string, CancellationToken)/CreateAccessTokenAsync(IOpenBiApiClient, string, string, string?, CancellationToken) (or SetAccessToken(string?) with a token obtained elsewhere) before calling any other domain's extension methods.

public static class OpenBiApiClientAuthExtensions

Inheritance

object

OpenBiApiClientAuthExtensions

Methods

CreateAccessTokenAsync(IOpenBiApiClient, string, string, string?, CancellationToken)

Authenticates as an API key via the OAuth2 client_credentials grant and attaches the resulting access token to client for subsequent requests. clientId and clientSecret are the key's Id and Secret. A scope, space delimited, narrows the token to part of what the key may do and may only name scopes the key lists and its user holds - so a key that lists none accepts no scope. Without one the token gets the key's scopes, or its user's permissions where the key names none - and never a permission the user does not hold.

public static Task<OAuthAccessToken> CreateAccessTokenAsync(this IOpenBiApiClient client, string clientId, string clientSecret, string? scope = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

clientId string

clientSecret string

scope string

cancellationToken CancellationToken

Returns

Task<OAuthAccessToken>

CreateAccessTokenFromAuthorizationCodeAsync(IOpenBiApiClient, string, string?, string, string?, string, CancellationToken)

Redeems the code an authorization request (GetAuthorizationUri(IOpenBiApiClient, string, string?, OAuthPkce, string?, string?, string?)) returned via the OAuth2 authorization_code grant, and attaches the access token to client. The token acts as the user who signed in; its RefreshToken gets the next one from RefreshAccessTokenAsync(IOpenBiApiClient, string, string?, string?, string?, CancellationToken). A code is good once, for five minutes.

public static Task<OAuthAccessToken> CreateAccessTokenFromAuthorizationCodeAsync(this IOpenBiApiClient client, string clientId, string? clientSecret, string code, string? redirectUri, string codeVerifier, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

The client to attach the access token to.

clientId string

The app's id.

clientSecret string

The app's secret; null for a public app, which has none.

code string

The code the redirect carried.

redirectUri string

The redirect URI the authorization request named, exactly - null where it named none.

codeVerifier string

The Verifier of the pair the request was made with.

cancellationToken CancellationToken

Cancels the request.

Returns

Task<OAuthAccessToken>

GetAuthorizationUri(IOpenBiApiClient, string, string?, OAuthPkce, string?, string?, string?)

Where an OAuth app sends the user's browser to start the authorization code flow: oauth/authorize on client's server. The user signs in there if need be and is asked to allow the app; then the browser comes back to redirectUri with a code and the state, which the app has to check is the one it sent. The code goes to CreateAccessTokenFromAuthorizationCodeAsync(IOpenBiApiClient, string, string?, string, string?, string, CancellationToken), with the verifier of pkce.

public static Uri GetAuthorizationUri(this IOpenBiApiClient client, string clientId, string? redirectUri, OAuthPkce pkce, string? state, string? scope = null, string? nonce = null)

Parameters

client IOpenBiApiClient

The client whose server the user signs in at.

clientId string

The app's id (Id).

redirectUri string

One of the app's redirect URIs, exactly; may be left out where it registered one only.

pkce OAuthPkce

A new OAuthPkce for this request.

state string

An unguessable value tying the answer to this request, against cross-site request forgery.

scope string

Space-delimited permission ids to narrow the token to; without it the token gets all the app may carry. With openid (and profile, email) the token response carries an OpenID Connect ID token as well.

nonce string

OpenID Connect: a value the ID token repeats, which the app checks against the one it sent.

Returns

Uri

GetCurrentUserInfoAsync(IOpenBiApiClient, CancellationToken)

Retrieves the authenticated user's basic profile information via GET /oauth/userinfo: who the current token belongs to, and whether it has to change its password first. Needs no permission, unlike GetUserAsync(IOpenBiApiClient, string, CancellationToken).

public static Task<OAuthUserInfo> GetCurrentUserInfoAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

cancellationToken CancellationToken

Returns

Task<OAuthUserInfo>

LoginAsync(IOpenBiApiClient, string, string, CancellationToken)

Authenticates as a user via the OAuth2 password grant and attaches the resulting access token to client for subsequent requests.

public static Task<OAuthAccessToken> LoginAsync(this IOpenBiApiClient client, string username, string password, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

username string

password string

cancellationToken CancellationToken

Returns

Task<OAuthAccessToken>

NegotiateAsync(IOpenBiApiClient, CancellationToken)

Signs on through the platform's own authentication - Kerberos or NTLM - via the negotiate grant, and attaches the resulting access token to client for subsequent requests.

public static Task<OAuthAccessToken> NegotiateAsync(this IOpenBiApiClient client, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

cancellationToken CancellationToken

Returns

Task<OAuthAccessToken>

Remarks

A handshake rather than a credential: the server answers the first call with a challenge, and the message handler underneath answers it. That only happens where the handler is allowed to - a System.Net.Http.HttpClientHandler needs System.Net.Http.HttpClientHandler.UseDefaultCredentials, and in a browser it is the browser that answers. A server not configured for single sign-on refuses the grant.

RefreshAccessTokenAsync(IOpenBiApiClient, string, string?, string?, string?, CancellationToken)

Gets a new access token via the OAuth2 refresh_token grant, and attaches it to client. The response carries a new RefreshToken in place of refreshToken: keep it, because using the old one again revokes the grant. A refresh token not used for 30 days expires. A scope narrows the token to part of what was granted.

public static Task<OAuthAccessToken> RefreshAccessTokenAsync(this IOpenBiApiClient client, string refreshToken, string? clientId = null, string? clientSecret = null, string? scope = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

The client to attach the access token to.

refreshToken string

The refresh token the last LoginAsync(IOpenBiApiClient, string, string, CancellationToken), NegotiateAsync(IOpenBiApiClient, CancellationToken), CreateAccessTokenFromAuthorizationCodeAsync(IOpenBiApiClient, string, string?, string, string?, string, CancellationToken) or refresh returned.

clientId string

The OAuth app's id, for a refresh token an app got - null for one from LoginAsync(IOpenBiApiClient, string, string, CancellationToken) or NegotiateAsync(IOpenBiApiClient, CancellationToken), which belongs to no app.

clientSecret string

The app's secret; null for a public app, or for no app.

scope string

Space-delimited permission ids to narrow the new token to.

cancellationToken CancellationToken

Cancels the request.

Returns

Task<OAuthAccessToken>

RevokeTokenAsync(IOpenBiApiClient, string, bool, CancellationToken)

Revokes an access or refresh token via POST /oauth/revoke - what a client calls on logout. A token that is unknown, expired or already revoked is accepted rather than reported, so revoking twice is safe. Revoking the client's own access token also drops it from the client: the server answers a revoked token with a 401 wherever it is sent, a sign-in among them.

public static Task RevokeTokenAsync(this IOpenBiApiClient client, string token, bool isRefreshToken = false, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

token string

isRefreshToken bool

cancellationToken CancellationToken

Returns

Task

SignOutEverywhereAsync(IOpenBiApiClient, IEnumerable<string>?, CancellationToken)

Signs the caller out everywhere (DELETE oauth/signins): every token and every session, or with grants (password, negotiate, client_credentials, authorization_code) only the tokens of those grants and the sessions they signed in. The client's own token is among them, so it has to sign in again.

public static Task SignOutEverywhereAsync(this IOpenBiApiClient client, IEnumerable<string>? grants = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

grants IEnumerable<string>

cancellationToken CancellationToken

Returns

Task

SignOutUserEverywhereAsync(IOpenBiApiClient, string, IEnumerable<string>?, CancellationToken)

Signs a user out everywhere (DELETE users/{id}/signins, needs openbi.user.write) - for an account that may be compromised. grants as for SignOutEverywhereAsync(IOpenBiApiClient, IEnumerable<string>?, CancellationToken).

public static Task SignOutUserEverywhereAsync(this IOpenBiApiClient client, string userId, IEnumerable<string>? grants = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

userId string

grants IEnumerable<string>

cancellationToken CancellationToken

Returns

Task