angular2-token-ionic3 v0.0.1

Angular2-Token-Ionic3

Token based authentication service for Ionic 3 Oauth inAppBrowser login (facebook, github, etc.). Basically just https://github.com/neroniaky/angular2-token with some logic added for ionic oauth. Angular2-Token-Ionic3 works best with the devise token auth gem for Rails.

Angular2-Token-Ionic3 is currently in Alpha. Use with caution.

NOTE: This package is here to solve our immediate auth needs. Hope to merge into https://github.com/neroniaky/angular2-token once the changes are more thoroughly tested.

Installation

Requirements

• Webpack (SystemJS not tested)

1. Install Angular2-Token-Ionic3 via NPM with

   npm install angular2-token-ionic3

2. Import and add Angular2TokenService to your main module. Angular2TokenService depends on HttpModule and RouterModule, so make sure you import them too.

   import { Angular2TokenService } from 'angular2-token';
   
   @NgModule({
       imports: [
           BrowserModule,
           HttpModule,
           RouterModule
       ],
       declarations: [ AppComponent ],
       providers:    [ Angular2TokenService ],
       bootstrap:    [ AppComponent ]
   })

3. Inject Angular2TokenService into your main component and call .init().

   constructor(private _tokenService: Angular2TokenService) {
       this._tokenService.init();
   }

Quickstart (αlpha)

Quickstart is currently in αlpha, please use with caution.

1. Add A2tUiModule to your main module.

   import { Angular2TokenService, A2tUiModule } from 'angular2-token';
   
   @NgModule({
       imports: [
           BrowserModule,
           HttpModule,
           RouterModule,
           A2tUiModule
       ],
       declarations: [ AppComponent ],
       providers:    [ Angular2TokenService ],
       bootstrap:    [ AppComponent ]
   })

The A2tUiModule adds the following routes to your project:

On successful sign in the user will be redirect to restricted.

Content

• Configuration
• Service Methods
  • .signIn()
  • .signOut()
  • .registerAccount()
  • .deleteAccount()
  • .validateToken()
  • .updatePassword()
  • .resetPassword()
  • .signInOAuth()
  • .processOAuthCallback()
• HTTP Service Wrapper
• Multiple User Types
• Route Guards
• Advanced Usage
  • .sendHttpRequest()
  • .userSignedIn()
  • .currentUserType
  • .currentUserData
  • .currentAuthData
• Common Problems
• Development
  • Testing
  • Credits
  • License

Configuration

Configuration options can be passed as Angular2TokenOptions via .init().

Default Configuration

constructor(private _tokenService: Angular2TokenService) {
    this._tokenService.init({
        apiBase:                    null,
        apiPath:                    null,

        signInPath:                 'auth/sign_in',
        signInRedirect:             null,
        signInStoredUrlStorageKey:  null,

        signOutPath:                'auth/sign_out',
        validateTokenPath:          'auth/validate_token',
        signOutFailedValidate:      false,

        registerAccountPath:        'auth',
        deleteAccountPath:          'auth',
        registerAccountCallback:    window.location.href,

        updatePasswordPath:         'auth',
        resetPasswordPath:          'auth/password',
        resetPasswordCallback:      window.location.href,

        oAuthBase:                  window.location.origin,
        oAuthPaths: {
            github:                 'auth/github'
        },
        oAuthCallbackPath:          'oauth_callback',
        oAuthWindowType:            'newWindow',
        oAuthWindowOptions:         null,
        oAuthBrowserCallback:       null,

        userTypes:                  null,

        globalOptions: {
            headers: {
                'Content-Type':     'application/json',
                'Accept':           'application/json'
            }
        }
    });
}

Global Options

Further information on paths/routes can be found at devise token auth

Service Methods

Once initialized Angular2TokenService offers methods for session management.

.signIn()

The signIn method is used to sign in the user with email address and password. The optional parameter type specifies the name of UserType used for this session.

signIn({email: string, password: string, userType?: string}): Observable<Response>

Example:

this._tokenService.signIn({
    email:    'example@example.org',
    password: 'secretPassword'
}).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.signOut()

The signOut method destroys session and session storage.

signOut(): Observable<Response>

Example:

this._tokenService.signOut().subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.registerAccount()

Sends a new user registration request to the Server.

registerAccount({email: string, password: string, passwordConfirmation: string, userType?: string}): Observable<Response>

Example:

this._tokenService.registerAccount({
    email:                'example@example.org',
    password:             'secretPassword',
    passwordConfirmation: 'secretPassword'
}).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.deleteAccount()

Deletes the account for the signed in user.

deleteAccount(): Observable<Response>

Example:

this._tokenService.deleteAccount().subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.validateToken()

Validates the current token with the server.

validateToken(): Observable<Response>

Example:

this._tokenService.validateToken().subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.updatePassword()

Updates the password for the logged in user. updatePassword({password: string, passwordConfirmation: string, passwordCurrent: string, userType?: string, resetPasswordToken?: string}): Observable<Response>

Example:

this._tokenService.updatePassword({
    password:             'newPassword',
    passwordConfirmation: 'newPassword',
    passwordCurrent:      'oldPassword',
    resetPasswordToken:   'resetPasswordToken',
}).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.resetPassword()

Request a password reset from the server.

resetPassword({email: string, userType?: string}): Observable<Response>

Example:

this._tokenService.resetPassword({
    email: 'example@example.org',
}).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.signInOAuth()

Initiates OAuth authentication flow. Currently, it supports two window modes: newWindow (default) and sameWindow (settable in config as oAuthWindowType).

• When oAuthWindowType is set to newWindow, .signInOAuth() opens a new window and returns an observable.

• When oAuthWindowType is set to sameWindow, .signInOAuth() returns nothing and redirects user to auth provider. After successful authentication, it redirects back to oAuthCallbackPath. Application router needs to intercept this route and call processOAuthCallback() to fetch AuthData from params.

signInOAuth(oAuthType: string)

Example:

this._tokenService.signInOAuth(
'github'
).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

.processOAuthCallback()

Fetches AuthData from params sent via OAuth redirection in sameWindow flow.

processOAuthCallback()

Example

Callback route:

RouterModule.forRoot([
  { path: 'oauth_callback', component: OauthCallbackComponent }
])

Callback component:

@Component({
  template: ''
})
export class OauthCallbackComponent implements OnInit {
  constructor(private _tokenService: Angular2TokenService) {}

  ngOnInit() {
    this._tokenService.processOAuthCallback();
  }
}

HTTP Service Wrapper

Angular2TokenService wraps all standard Angular2 Http Service calls for authentication and token processing. If apiPath is configured it gets added in front of path.

• get(url: string, options?: RequestOptionsArgs): Observable<Response>
• post(url: string, body: any, options?: RequestOptionsArgs): Observable<Response>
• put(url: string, body: any, options?: RequestOptionsArgs): Observable<Response>
• delete(url: string, options?: RequestOptionsArgs): Observable<Response>
• patch(url: string, body: any, options?: RequestOptionsArgs): Observable<Response>
• head(url: string, options?: RequestOptionsArgs): Observable<Response>
• options(url: string, options?: RequestOptionsArgs): Observable<Response>

Example:

this._tokenService.get('my-resource/1').map(res => res.json()).subscribe(
    res =>      console.log(res),
    error =>    console.log(error)
);

Multiple User Types

An array of UserType can be passed in Angular2TokenOptions during init(). The user type is selected during sign in and persists until sign out. .currentUserType returns the currently logged in user.

Example:

this._tokenService.init({
    userTypes: [
        { name: 'ADMIN', path: 'admin' },
        { name: 'USER', path: 'user' }
    ]
});

this._tokenService.signIn({
    email:    'example@example.com',
    password: 'secretPassword',
    userType: 'ADMIN'
})

this._tokenService.currentUserType; // ADMIN

Route Guards

Angular2-Token-Ionic3 implements the CanActivate interface, so it can directly be used as a route guard. If the signInRedirect option is set the user will be redirected on a failed (=false) CanActivate using Router.navigate(). It currently does not distinguish between user types.

Example:

const routerConfig: Routes = [
    {
        path: '',
        component: PublicComponent
    }, {
        path: 'restricted',
        component: RestrictedComponent,
        canActivate: [Angular2TokenService]
    }
];

Advanced Usage

More advanced methods can be used if a higher degree of customization is required.

.request()

More customized requests can be send with the .request()-function. It accepts the RequestOptionsArgs-Interface. More information can be found in the Angular2 API Reference here.

request(options: RequestOptionsArgs): Observable<Response>

Example:

this._tokenService.request({
    method: RequestMethod.Post,
    url:    'my-resource/1',
    data:   mydata
});

.userSignedIn()

Returns true if a user is signed in. It does not distinguish between user types.

userSignedIn(): boolean

.currentUserType

Returns current user type as string like specified in the options.

get currentUserType(): string

.currentUserData

Returns current user data as returned by devise token auth. This variable is null after page reload until the .validateToken() call is answerd by the backend.

get currentUserData(): UserData

.currentAuthData

Returns current authentication data which are used to set auth headers.

get currentAuthData(): AuthData

.currentAuthHeaders

Returns current authentication data as an HTTP ready Header object.

get currentAuthHeaders(): Header

Redirect original requested URL

If you want to redirect to the protected URL after signing in, you need to set signInStoredUrlStorageKey and in your code you can do something like this

this._tokenService.signIn({
    email:    'example@example.org',
    password: 'secretPassword'
}).subscribe(
    res => {
        // You have to add Router DI in your component
        this.router.navigateByUrl(localStorage.getItem('redirectTo'));
    },
    error =>    console.log(error)
);

Common Problems

CORS Configuration

If you are using CORS in your Rails API make sure that Access-Control-Expose-Headers includes access-token, expiry, token-type, uid, and client. For the rack-cors gem this can be done by adding the following to its config. More information can be found here.

```ruby
:expose  => ['access-token', 'expiry', 'token-type', 'uid', 'client']
```

Missing Routes

Make sure that your projects includes some kind of routing.

Credits

Ripped off almost entirely from https://github.com/neroniaky/angular2-token with some logic bits mashed about for ionic 3 oauth.

License

The MIT License (see the LICENSE file for the full text)