This is a plugin that only has a peer dependency to
piral-oidc brings to the table is a direct integration with OpenID Connect identity providers on basis of the oidc-client library that can be used with
The set includes the
getAccessToken API to retrieve the current user's access token, as well as
getProfile to retrieve the current user's open id claims.
By default, these Pilet API extensions are not integrated in
piral, so you'd need to add them to your Piral instance.
The following functions are brought to the Pilet API.
Gets a promise for the currently authenticated user's token or
undefined if no user is authenticated.
Gets a promise for the currently authenticated user's open id claims. Rejects if the user is expired or not authenticated.
::: summary: For pilet authors
You can use the
getAccessToken function from the Pilet API. This returns a promise.
Note that this value may change if the Piral instance supports an "on the fly" login (i.e., a login without redirect / reloading of the page).
If you need to use claims from the authentication:
::: summary: For Piral instance developers
The provided library only brings API extensions for pilets to a Piral instance.
For the setup of the library itself you'll need to import
createOidcApi from the
Custom claims are supported by declaration merging. Reference the
types module in typescript and
merge into the PiralCustomOidcProfile.
The integration looks like:
;// These should match what your server providesdeclare;;
The separation into
createOidcApi was done to simplify the standard usage.
Normally, you would want to have different modules here. As an example consider the following code:
// module oidc.ts;;// app.ts;;// index.ts;if location.pathname !== '/auth'
This way we evaluate the current path and act accordingly. Note that the actually used path may be different for your application.
Built-in authentication flow
A convenience method named
handleAuthentication() was added to the
handle callbacks and routing for you. In order to use this, add a
appUrl to the
client configuration that points to your entry-point route, and then call
handleAuthentication() in your index file.
handleAuthentication() will return a promise that resolves to an
result.shouldRender is true, the application should call
render(), when false, do nothing (this is a silent renew happening in the background).
If the promise rejects, it is advised that the error is logged to an external logging service, as this indicates a user that could not gain entry into the application. Afterwards, call
logout() or prompt the user for the next action.
// module oidc.ts;;// app.ts;;// index.ts;;client.handleAuthentication.then.catch
Retaining state between sign in request and the callback
You can pass the
signInRedirectParams which will be passed
to the signInRedirect method.
After properly signing in, the
state param will be available when the callback method is finally
reached. This can be used to do things such as redirecting to an originally visited URL that
can no longer be referenced due to jumping between your app and the auth pages.
// module oidc.ts;;// index.ts;client.handleAuthentication.then
Piral is released using the MIT license. For more information see the license file.