From f8e11001f560bdbf53a8e0f55f56eb84748b3b4a Mon Sep 17 00:00:00 2001 From: Jordan Melberg Date: Mon, 5 Mar 2018 17:11:25 -0800 Subject: [PATCH] docs: Updates README with method signatures (#136) Resolves: OKTA-161320 --- packages/okta-angular/README.md | 208 +++++++++++++++++++++++--------- 1 file changed, 148 insertions(+), 60 deletions(-) diff --git a/packages/okta-angular/README.md b/packages/okta-angular/README.md index 5e8b8f19b..7087d1ac4 100644 --- a/packages/okta-angular/README.md +++ b/packages/okta-angular/README.md @@ -1,62 +1,103 @@ # Okta Angular SDK -The Okta Angular SDK is a wrapper around [Okta Auth JS](https://github.com/okta/okta-auth-js), that builds on top of Okta's [OpenID Connect API](https://developer.okta.com/docs/api/resources/oidc.html). +An Angular (4+) wrapper around [Okta Auth JS](https://github.com/okta/okta-auth-js), that builds on top of Okta's [OpenID Connect API](https://developer.okta.com/docs/api/resources/oidc.html). This library currently supports: - [OAuth 2.0 Implicit Flow](https://tools.ietf.org/html/rfc6749#section-1.3.2) ## Getting Started * If you do not already have a **Developer Edition Account**, you can create one at [https://developer.okta.com/signup/](https://developer.okta.com/signup/). -* If you don't have an Angular app, or are new to Angular, please start with the [Angular Quickstart](https://angular.io/guide/quickstart) guide. It will walk you through the creation of an Angular app, creating routes, and other application development essentials. +* An Okta Application, configured for Singe-Page App (SPA) mode. This is done from the Okta Developer Console and you can find instructions [here](https://developer.okta.com/authentication-guide/implementing-authentication/implicit#1-setting-up-your-application). When following the wizard, use the default properties. They are are designed to work with our sample applications. -### Add an OpenID Connect Client in Okta -In Okta, applications are OpenID Connect clients that can use Okta Authorization servers to authenticate users. Your Okta Org already has a default authorization server, so you just need to create an OIDC client that will use it. -* Log into the Okta Developer Dashboard, click **Applications** > **Add Application**. -* Choose **Single Page App (SPA)** as the platform, then submit the form the default values, which should look like this: - -| Setting | Value | -| ------------------- | ---------------------------------------------- | -| App Name | My SPA App | -| Base URIs | http://localhost:{port} | -| Login redirect URIs | http://localhost:{port}/implicit/callback | -| Grant Types Allowed | Implicit | - -After you have created the application there are two more values you will need to gather: - -| Setting | Where to Find | -| ------------- | ------------------------------------------------------------------------------ | -| Client ID | In the applications list, or on the "General" tab of a specific application. | -| Org URL | On the home screen of the developer dashboard, in the upper right. | - - -These values will be used in your Angular application to setup the OpenID Connect flow with Okta. +### Helpful Links +- [Angular Quickstart](https://angular.io/guide/quickstart) + - If you don't have an Angular app, or are new to Angular, please start with this guide. It will walk you through the creation of an Angular app, creating routes, and other application development essentials. +- [Okta Sample Application](https://github.com/okta/samples-js-angular) + - A fully functional sample application. +- [Okta Angular Quickstart](https://okta.github.io/quickstart/#/angular/nodejs/generic) + - Helpful resource for integrating an existing Angular application into Okta. ## Installation - This library is available through [npm](https://www.npmjs.com/package/@okta/okta-angular). To install it, simply add it to your project: ```bash npm install --save @okta/okta-angular ``` -### Configuration -You will need the values from the OIDC client that you created in the previous step to instantiate the middleware. You will also need to know your Okta Org URL, which you can see on the home page of the Okta Developer console. +## Usage +`okta-angular` works directly with [`@angular/router`](https://angular.io/guide/router) and provides the additional components and services: +- [`OktaAuthModule`](#oktaauthmodule) - Allows you to supply your OpenID Connect client configuration. +- [`OktaAuthGuard`](#oktaauthguard) - A navigation guard using [CanActivate](https://angular.io/api/router/CanActivate) to grant access to a page only after successful authentication. +- [`OktaCallbackComponent`](#oktacallbackcomponent) - Handles the implicit flow callback by parsing tokens from the URL and storing them automatically. +- [`OktaLoginRedirectComponent`](#oktaloginredirectcomponent) - Redirects users to the Okta Hosted Login Page for authentication. +- [`OktaAuthService`](#oktaauthservice) - Highest-level service containing the `okta-angular` public methods. -In your application's `module.ts` file, create a configuration object: +### `OktaAuthModule` +The `OktaAuthModule` is the initializer for your OpenID Connect client configuration. It accepts the following properties: + - `issuer` **(required)**: The OpenID Connect `issuer` + - `clientId` **(required)**: The OpenID Connect `client_id` + - `redirectUri` **(required)**: Where the callback is hosted + - `scope` *(optional)*: Reserved for custom claims to be returned in the tokens + - `onAuthRequired` *(optional)*: Accepts a callback to make a decision when authentication is required. If not supplied, `okta-angular` will redirect directly to Okta for authentication. ```typescript // myApp.module.ts +import { + OktaAuthModule +} from '@okta/okta-angular'; + const oktaConfig = { issuer: 'https://{yourOktaDomain}.com/oauth2/default', redirectUri: 'http://localhost:{port}/implicit/callback', clientId: '{clientId}' } + +const appRoutes: Routes = [ + ... +] + +@NgModule({ + imports: [ + ... + OktaAuthModule.initAuth(oktaConfig) + ], +}) +export class MyAppModule { } +``` + +### `OktaAuthGuard` +Routes are protected by the `OktaAuthGuard`, which verifies there is a valid `accessToken` stored. To ensure the user has been authenticated before accessing your route, add the `canActivate` guard to one of your routes: + +```typescript +// myApp.module.ts + +import { + OktaAuthGuard, + ... +} from '@okta/okta-angular'; + +const appRoutes: Routes = [ + { + path: 'protected', + component: MyProtectedComponent, + canActivate: [ OktaAuthGuard ] + }, + ... +] ``` -### Create the Callback Handler +If a user does not have a valid session, they will be redirected to the Okta Login Page for authentication. Once authenticated, they will be redirected back to your application's **protected** page. + +### `OktaCallbackComponent` In order to handle the redirect back from Okta, you need to capture the token values from the URL. You'll use `/implicit/callback` as the callback URL, and specify the default `OktaCallbackComponent` and declare it in your `NgModule`. ```typescript +// myApp.module.ts +import { + OktaCallbackComponent, + ... +} from '@okta/okta-angular'; + const appRoutes: Routes = [ { path: 'implicit/callback', @@ -74,47 +115,38 @@ const appRoutes: Routes = [ }) ``` -### Add a Protected Route -Routes are protected by the `OktaAuthGuard`, which verifies there is a valid `accessToken` stored. To ensure the user has been authenticated before accessing your route, add the `canActivate` guard: +### `OktaLoginRedirectComponent` +By default, the `OktaLoginRedirect` component redirects users to your Okta organization for login. Simply import and add it to your `appRoutes` to offset authentication to Okta entirely: ```typescript -{ - path: 'protected', - component: MyProtectedComponent, - canActivate: [ OktaAuthGuard ] -} -``` - -If a user does not have a valid session, they will be redirected to the Okta Login Page for authentication. Once authenticated, they will be redirected back to your application's **protected** page. - -### Update your `NgModule` -Finally, import the `OktaAuthModule` into your `NgModule`, and instantiate it by passing in your configuration object: +// myApp.module.ts +import { + OktaLoginRedirectComponent, + ... +} from '@okta/okta-angular'; -```typescript -@NgModule({ - imports: [ - ... - RouterModule.forRoot(appRoutes), - OktaAuthModule.initAuth(oktaConfig) - ], -}) -export class MyAppModule { } +const appRoutes: Routes = [ + { + path: 'login', + component: OktaLoginRedirectComponent + }, + ... +] ``` -### Reference -**Configuration Options** - - `issuer` **(required)**: The OpenID Connect `issuer` - - `clientId` **(required)**: The OpenID Connect `client_id` - - `redirectUri` **(required)**: Where the callback is hosted - - `scope` *(optional)*: Reserved or custom claims to be returned in the tokens - - `onAuthRequired` *(optional)*: Accepts a callback to make a decision when authentication is required. If not supplied, `okta-angular` will redirect directly to Okta for authentication. - -### Using a custom login-page +#### Using a custom login-page The `okta-angular` SDK supports the session token redirect flow for custom login pages. For more information, [see the basic Okta Sign-in Widget functionality](https://github.com/okta/okta-signin-widget#new-oktasigninconfig). To handle the session-token redirect flow, you can modify the unauthentication callback functionality by adding a `data` attribute directly to your `Route`: ```typescript +// myApp.module.ts + +import { + OktaAuthGuard, + ... +} from '@okta/okta-angular'; + export function onAuthRequired({oktaAuth, router}) { // Redirect the user to your custom login page router.navigate(['/custom-login']); @@ -144,6 +176,62 @@ const oktaConfig = { }; ``` +### `OktaAuthService` +In your components, your can take advantage of all of `okta-angular`'s features by importing the `OktaAuthService`. The example below shows connecting two buttons to handle **login** and **logout**: + +```typescript +// sample.component.ts + +import { OktaAuthService } from '@okta/okta-angular'; + +@Component({ + selector: 'app-component', + template: ` + + + + `, +}) +export class MyComponent { + + constructor(public oktaAuth: OktaAuthService) { + // ... + } +} +``` + +#### `oktaAuth.loginRedirect(additionalParams?)` +Performs a full page redirect to Okta based on the initial configuration. + +The optional parameter `additionalParams` is mapped to the [AuthJS OpenID Connect Options](https://github.com/okta/okta-auth-js#openid-connect-options). This will override any existing [configuration](#configuration). As an example, if you have an Okta `sessionToken`, you can bypass the full-page redirect by passing in this token. This is recommended when using the [Okta Sign-In Widget](https://github.com/okta/okta-signin-widget). Simply pass in a `sessionToken` into the `loginRedirect` method follows: + +```typescript +this.oktaAuth.loginRedirect({ + sessionToken: /* sessionToken */ +}) +``` + +> Note: For information on obtaining a `sessionToken` using the [Okta Sign-In Widget](https://github.com/okta/okta-signin-widget), please see the [`renderEl()` example](https://github.com/okta/okta-signin-widget#rendereloptions-success-error). + +#### `oktaAuth.isAuthenticated()` +Returns `true` if there is a valid access token or ID token. + +#### `oktaAuth.getAccessToken()` +Returns the access token from storage (if it exists). + +#### `oktaAuth.getIdToken()` +Returns the ID token from storage (if it exists). + +#### `oktaAuth.getUser()` +Returns the result of the OpenID Connect `/userinfo` endpoint if an access token exists. + +#### `oktaAuth.handleAuthentication()` +Parses the tokens returned as hash fragments in the OAuth 2.0 Redirect URI, then redirects to the URL specified when calling `loginRedirect`. + +#### `oktaAuth.logout()` +Terminates the user's session in Okta and clears all stored tokens. + ## Development 1. Clone the repo: - `git clone git@github.com:okta/okta-oidc-js.git` @@ -161,4 +249,4 @@ const oktaConfig = { | `npm start` | Start the sample app using the SDK | | `npm test` | Run integration tests | | `npm run lint` | Run eslint linting tests | -| `npm run docs` | Generate typedocs | \ No newline at end of file +| `npm run docs` | Generate typedocs |