search

michaelschnyder / oidc-angular

AngularJS Library for token based authentication
MIT License
24 stars 21 forks source link

readme

oidc-angular

This is an angularjs client library to support modern web-applications when using the OpenId compatible "Hyprid Flow" aka "Browser-Flow". See http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth for details.

Hybrid Flow explained

See origin on http://blog.emtwo.ch/jwt-token-based-auth-with-angularjs/ for motivation and technical details.

Getting started

To install oidc-angular use bower

bower install oidc-angular -save

Inject the $auth-provider to setup the library while configuring your angular-application


var app = angular.module('myApp', ['oidc-angular'], function($auth) {
  $auth.configure(
    {
      clientId: 'abcd...',
      ...
    }
  );
}
);

Configuration Options

For a complete and always up-to-date list of configuration options, see https://github.com/michaelschnyder/oidc-angular/blob/master/oidc-angular.js#L220.

Option Type Description Default Value
basePath string Path to the OIDC-Compatible Identity Provider. Will be used as the baseUrl for the authorizationEndpoint and endSessionEndpoint none
clientId string The identifier of the client application. See Spec none
apiUrl string The url to your backend which should be protected by adding the jwt-token for outgoing requests. /api/
responseType string Type of the required token. Should be id_token. id_token
scope string Scopes (and contained claims) that should be returned by the IdP. Needs to be at least openid profile. Separate by space. openid profile
redirectUri string The uri where the Library has registered its callback route for login is by default #/auth/callback/. The callback route gets evaluated by the Library and typically doesn't need an adjustment [Proto]://[HostName]/[Path(s)]/#/auth/callback/
logoutUri string The uri where the Library has registered its callback route for logout is by default #/auth/clear. The callback route gets evaluated by the Library and typically doesn't need an adjustment [Proto]://[HostName]/[Path(s)]/#/auth/clear
authorizationEndpoint string Place where the user logs in to the IdP. Combined with basePath [basePath]:connect/authorize
endSessionEndpoint string Place where the ends his session in the IdP. Combined with basePath [basePath]:connect/endsession
advanceRefresh int Defines the advance seconds when trying to silenty reaquire a token. Checks are not made constantly, only after on sucessfull responses 300
enableRequestChecks boolean Specifies if the token should be validated before using it in outgoing requests. Use with caution, because this checks depend on the currect UTC time of both the browser and the server false
stickToLastKnownIdp boolean Defines if the user should pass the last used IdP Name with the authorization request so that a front facing authorization decision server could automatically redirect to the propper IdP. This option might only be usful when using an primary IdP with additional "child"-IdPs. See 'acr_values' on IdentityServer Docs false

Configuring the IdP

When configuring the IdP, make sure the options clientId, redirectUri and logoutUri are exact the same as in the oidc-angular configuration. Otherwise, the IdP typically refuses to redirect back to your application as part of its security restrictions.

Events

oidc-angular comes with a various list of events which gives you the most possible flexibility to handle the authentication process

Events are broadcasted to the $rootScope.

Name Description Parameters
oidcauth:unauthorized The server returned an 401 response and oidc-angular was unable to find out the exect reason. See tokenExpired or tokenMissing The response istelf
oidcauth:tokenExpired The server returned an 401 response and the lib found out that the token might be expired. request or response, see enableRequestChecks
oidcauth:tokenMissing The server returned an 401 response while the client had no token sent. request or response, see enableRequestChecks
oidcauth:tokenExpires Raised when the token will expire soon, based on the value of advanceRefresh none
oidcauth:loggedIn Raised when the library sucessfully parsed the token after the IdP-Redirect none
oidcauth:loggedOut Raised when the IdP redirected the user back to the app after logout none
oidcauth:silentRefreshStarted The Refresh-process of the token has started in the background (iframe) none
oidcauth:silentRefreshSucceded A new and newer token was aquired sucessfully none
oidcauth:silentRefreshFailed Unable to aquire a new token via background-process none
oidcauth:silentRefreshTimeout The background-refresh process timed out none

Methods

SignIn

Redirects the user to the configured IpP. The URL to the login screen is constructed based on the configuration made.

Samples

 $auth.signIn();

Or with a redirection after login:

 $auth.signIn('#/page2');

SignOut

Logout the user imediately and quit the session on the IdP by calling the endSessionEndpoint. Claims in local storage get cleared after callback.

Sample

 $auth.signOut();

IsAuthenticated

Returns true if the there is a valid token available, false if no token or an expired / not yet valid token is available.

Sample

 $auth.isAuthenthicated();

IsAuthenticatedIn(milliseconds)

Returns true if the current token is still valid after the given amount of milliseconds

Sample

 $auth.isAuthenthicatedIn(3600000); // 1hour

Sample

There is a sample in the samples-Folder.

Compatibility

This library has been tested and intensively used with the ThinkTecture IdentityServer3 with various versions. Please see Thinktecture IdentityServer3 for further details.