ng-gpoauth
is a client side (brower hosted) framework agnostic (to some degree) implementation for client
side code that works together with node-gpoauth server side Oauth2 integration. ng-gpoauth
does the following things in the broswer:
- Checks for and Validates Oauth2 tokens sent from server.
- Stores up-to-date access tokens in the browser
- Facilitates initiating auth actions in browser (initiate login, initiate logout)
- Emits messages for auth related events (login, logout, etc.)
There are two major types of authentication:
Token or implicit type authentication does not require or use a back end service for authentication. The entire authentication process will be handled between the Oauth provider and front end application hosting ng-gpoauth
.
Grant type authentication require a back end service (like node-gpoauth) to handle receiving JWT and related tokens from the OAuth provider.
NOTE: For security reasons the JWT stored in local storage is scrambled. Passing the encoded value in the Authorization header will not validate server side.
npm install http://github.com/GeoPlatform/ng-gpoauth.git
See the Configuration section for options.
ng-gpoauth
exposes a service facotry that can be used to create a service used in angularJS applications. The basic workflow is to utilize the ServiceFactory to make your own service that is used in the application.
Setup the service in app.js:
// app.js
angular.module('myApp', ['gp-gpoauth', ...])
.config(function(){
// your configs and other init.
});
// Register wrapper service for dependency injection.
angular.module('gp-gpoauth')
.service('AuthenticationService', function($injector){
const authServiceFact = $injector.get('ng-authServiceFactory');
// pull in your custom settings
const myAuthSettings = {
//...
}
// Create a new Service that any directive/controller/service can load
return authServiceFact(myAuthSettings)
});
Use the service in a component/module/etc.:
// myModule.js
angular.module('myModule', [])
.controller('myController', ['AuthenticationService', function(AuthenticationService){
// Interact with ng-gpoauth service
AuthenticationService.login()
}])
ng-gpoauth
exposes a service that can be utilized thought out Angular 5+ application.
You will first need to register a provider for using AuthService
with Dependency Injection.
NOTE: The import is
ng-gpoauth/angular
for Angular 5+
// app.module.ts
import { ngGpoauthFactory, AuthService } from 'ng-gpoauth/angular';
import { TokenInterceptor } from 'ng-gpoauth/angular'
/**
* Configuration object for ng-gpoauth. See the Configuration section below
* for a list of options.
*
* @see https://github.com/GeoPlatform/ng-gpoauth#configuration
*/
import { authConfig } from './myConfig';
// Pass settings in : get Auth Service back
const authService = ngGpoauthFactory(authConfig);
// ...
@NgModule({
declarations: [...],
imports: [...],
providers: [
// Use the service we created `authService` as `AuthService` when injecting
{
provide: AuthService,
useValue: authService
},
// Setup handler for sending and receiving tokens from backend service
{
provide: HTTP_INTERCEPTORS,
useClass: TokenInterceptor,
multi: true
}
...
],
bootstrap: [AppComponent]
})
Using in a component:
// app.component.ts
import { AuthService, GeoPlatformUser } from 'ng-gpoauth/angular'
@Component({...})
export class AppComponent {
constructor(private authService : AuthService) {
authService.getUser().then( user => {
// I have the user!
})
}
}
All versions of ng-gpoauth
have messages associated with authentication events. Each implementation provides its on messaging system for subscribing to these events. This is an example of how the Event Messenger can be obtained and used:
const authMsg = authService.getMessenger()
authMsg.on('userAuthenticated', (evt, user) => {
// TODO: react to user authenticated even here
})
authMsg.on('userSignOut', (evt) => {
// TODO: react to user sign out event here
})
The Angular (5+) can use the raw()
method to obtain the raw rxjs
Subscription related to auth events:
import { Subject } from 'rxjs'
// AuthService init code ...
const sub = authService
.getMessenger()
.raw()
// Subscribe to all messages
sub.subscribe(msg => {
switch(msg.name){
case 'userAuthenticated':
// do something..
let user = msg.user;
break;
case 'userSignOut':
// do something else
break;
}
})
// --- or ---
// Break out specific message
const authenticated = sub.pipe(filter(msg => msg.name === 'userAuthenticated'))
authenticated.subscribe(msg => {
let user = msg.user;
})
name | description | args |
---|---|---|
auth:requireLogin | This event is used internally by ng-gpoauth . It will trigger the login event (either iframe login or redirect based on confuguration). |
event: the event |
userAuthenticated | Is called when a user has authenticated and the iframe authentication window is closed, or user has signed out. In the later case null will be passed for the user argument. | event: the event user: User object (or null) |
userSignOut | Is called when user is signed out. This can happen when the user triggers the logout action, or when an expired JWT is detected that is not able to be refreshed. | event: the event |
auth:iframeLoginShow | This event will be called when the login iframe is triggered. Use this event to inform your appliction that the login iframe is present. | event: the event |
auth:iframeLoginHide | This event is called when the loggin iframe is hidden. Use this event to inform your appliction that the login iframe has been hidden (NOTE: this will always fire when the login iframe is removed but the 'userAuthenticated' event will only fire is the user successfully logs in. If this event fires and the 'userAuthenticated' event does not it means the user canceled the login challenge). | event: the event |
The following are property on the config object passed into ng-gpoauth
(see the USAGE section for integration details):
property | required | description | type | default |
---|---|---|---|---|
IDP_BASE_URL | yes | URL of the Oauth serice. | string | N/A |
APP_ID | yes* | Id (client_id) of appliction registerd with the Oauth service provider. | string | N/A |
APP_BASE_URL | no | Allows for settings a URL prefix checking node-gpoauth endpoints like /checktoken . Can be either an absolute or relative path to prefix to reqeusts: Example: '/authendpoints' |
string | "" |
AUTH_TYPE | no | Type of token to request from gpoauth. | token, grant | grant |
ALLOW_IFRAME_LOGIN | no | Allow ng-gpoauth to use an ifame instead of redirect for authenticating a user. This will allow users to retain their in-memory edits while authenticating. |
boolean | false |
FORCE_LOGIN | no | Should user be forced to redirct or show login screen when its detected that they are unauthenticated | boolean | false |
CALLBACK | no | URL to call back when re-directed from oauth authentication loop. | string | /login |
LOGIN_URL | no | URL to redirect browser to when auth type is 'token'. | string | /login |
LOGOUT_URL | no | Url to redirec user to when they preform the logout action. | string |
* only required configuration when authorization is type token
(implicit, no backend server support).