This is the Javascript client library to simplify integration of pCon.login services into your web application.
Its main purpose is the implementation of the Authorization Code Flow with PKCE. For details regarding pCon.login, OAuth and Authorization Code Flow, please refer to
https://login.pcon-solutions.com/doc/api/oauth2.html and https://tools.ietf.org/html/rfc6749#page-24.
Supported Browsers
Not supported
Usage in iframe
Usage in iframes is not supported, as 3rd Party Cookies are required, which are disabled on many browser instances by default (e.g. on Apple devices).
Local/Session Storage
The library requires both Local and Session Storage to work properly.
Typical usage of the library will look like this:
Create a OAuthOptions object, specifying your client_id and redirect_uri.
const oauthOptions = {
client_id: YOUR_CLIENT_ID,
redirect_uri: YOUR_REDIRECT_URI
};
Create an instance of the PConLoginClient with the oauthOptions:
const loginClient = new PConLogin.PConLoginClient(oauthOptions);
Call the loginWithRedirect method of the PConLoginClient object. To simplify redirection after logging in, you can provide your target page as the optional next parameter which will be stored for future use. If the next parameter is not provided, the current location will be stored.
loginClient.loginWithRedirect(nextPage);
This will redirect the browser to the authorization endpoint and if the user is not logged in to pCon.login in this browser, it will ask the user to login.
The authorization endpoint will redirect the browser to your redirect_uri. On this page, you should call handleRedirect, which will execute the rest of the OAuth Flow and retrieve the access token. This function will return a Promise, which will resolve, when the process has finished. You can then call redirectToNext to redirect to your original application page.
loginClient.handleRedirect().then(() => {
loginClient.redirectToNext();
});
An alternative to the login process with redirect, is using a Popup. For this method, the steps after 2. could look as follows. It's recommended to open the popup in the "click" event handler of a button or similar, as some browsers will block popup if they are not opened by user interaction.
Open the popup with an empty page in event handler:
function onLoginBtnClicked()
{
let popup = window.open("about:blank");
Get the URI for the authorization endpoint, using the async method getAuthorizationURI and assign the location of the popup to the URI:
loginClient.getAuthorizationURI().then((authorizationURI) => {
popup.location = authorizationURI;
});
} // onLoginBtnClicked
This will open the same page as loginWithRedirect, but in a new tab or window and will again redirect to your redirect_uri in your popup.
In your popup you call handleRedirect. After the method returns and its Promise is resolved, you should close the popup. You will also need a way to notify your application, that there is an access token available. For this purpose you can create a callback in your main tab, that you call from your popup, after the redirect has been handled. In the callback, you should call handlePopupFinished which will load the tokens retrieved by the popup.
On main page:
// On main page code
window.loginCallback = () => {
loginClient.handlePopupFinished();
};
In popup:
loginClient.handleRedirect().then(() => {
window.opener.loginCallback();
window.close();
});
Step 1. and 2. have to be executed in every script you need the loginClient, i.e.:
After the login process has been executed successfully, you can do calls to pCon services, using the access token. You can either get the access token directly using getAccessToken, which will resolve to the access token, if there is a valid access token available, or null otherwise:
loginClient.getAccessToken().then((accessToken) => {
// Use access token for API call here
});
Or even easier, using fetchWithAuth, which you can use like the built-in browser function fetch (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and which automatically adds the Authorization header necessary for calls to pCon APIs.
loginClient.fetchWithAuth(apiEndpoint).
.then(() => {
// handle response here
}
);
The method you choose depends on the implementation of your application, so you will probably already know which method you need or prefer. The main advantage of the popup is, your application doesn't have to worry about losing its state, but the browser has to allow popups. With redirection if you want to persist your application state over redirects, you will have to provide your own implementation for persisting state.
As user sessions and access tokens can get invalidated outside the library, e.g. by logging out in another tab or on password change, the access token returned by the library can not be guaranteed to be valid. To avoid redundant requests, the library will only check, if there is an access token and if it should still be valid, according to the duration provided in the "expires_in" field of the server response.
null, there is no valid access token. In this case, the library will already have tried to refresh the access token using the refresh token.In both cases, you will want to trigger the login process again.
If you want to logout the user, there are two ways:
/logout page. This will logout the user from the session, so this will affect other applications, too. If you want be redirected back to your application, you can specify this by providing the next parameter to the logout function./revoke_token endpoint. This will keep the session with the pCon.login service alive for other tabsNote
If you're calling logout in a Single Page Application, the application will lose its state, due to the redirect, so you should make sure to store your state, if you need it after the logout.
Generated using TypeDoc