npm package: @softheon/armature-saml
Description: This library includes functionality for generating a SAML that will be used to redirect the user from one Softheon Armature Site to another.
Latest version: 0.0.13

# Saml

This library includes functionality for generating a SAML that will be used to redirect the user from one Softheon Armature Site to another.

## Usage

### Include the module

First, include the following module import in your angular root module.

```javascript
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    SamlModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }
```

### Embed the component

Next, embed the component. The component has the functionality to retrieve the SAML OnInit.

```html
<div>
  <saml-redirect-saml [request]="request" [samlGetEndpointUri]="urlForGeneratingRedirectSaml" [samlPostUrl]="urlToPostSamlTo" (isSamlGeneratedEvent)="postSaml()"></saml-redirect-saml>
</div>
```

### Hook into the output event to post the SAML

Then in the typescript, to trigger the redirect, do the following. This utilizes the `isSamlGeneratedEvent` shown above

```javascript
/** The app component */
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  /** The application title */
  public title: string = 'Armature';

  /**
   * Constructs the component
   * @param samlService The saml service
   */
  constructor(
    private readonly samlService: AbstractSamlService
  ) {}

  /** Posts the saml */
  public postSaml(): void {
    this.samlService.shouldPostSaml.next(true);
  }
}
```

## API - Components

### RedirectSamlComponent

#### Properties

| Name                                                    | Description                                               |
| ------------------------------------------------------- | --------------------------------------------------------- |
| `@Input() public request: RedirectSamlRequest`          | The request used for generating the saml                  |
| `@Input() public samlGetEndpointUri: string`            | The endpoint used for generating the SAML Response        |
| `@Input() samlPostUrl: string`                          | The endpoint to post the SAML Response to                 |
| `@Output() samlPostEvent: EventEmitter<boolean>`        | Event emitter indicating when the SAML has been posted    |

#### Models

##### ISamlRequest

| Name                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `redirectUrl: string` | The redirect URL used for generating the SAML (Audience and Destination nodes) |

##### RedirectSamlRequest implements ISamlRequest

| Name                    | Description                                                                    |
| ----------------------- | ------------------------------------------------------------------------------ |
| `redirectUrl: string`   | The redirect URL used for generating the SAML (Audience and Destination nodes) |
| `returnUrl: string`     | The URl to be used on the other site in case of return                         |
| `oAuthIssuer: string`   | The issuer for configuring OAuth 2.0                                           |
| `oAuthClientId: string` | The Client ID used OAuth 2.0 Implicit flow                                     |
| `oAuthScopes: string`   | The scopes used for the OAuth 2.0 configuration                                |
| `logo: string`          | The logo location for branding the site                                        |
| `theme: string`         | The theme name for branding the site                                           |
| `themeCDN: string`      | The CDN URL for the theme                                                      |
| `referenceId: string`   | The reference ID for the redirect                                              |
| `referenceData: string` | The reference data for the redirect                                            |

## API - Services

### Abstract SAML Service

#### Properties

| Name                                 | Description                                                |
| ------------------------------------ | ---------------------------------------------------------- |
| `postSaml$: Observable<string>`      | Observable indicating the provided SAML should be posted   |
| `postSaml: BehaviorSubject<boolean>` | BehaviorSubject for controlling what SAML should be posted |

#### Methods

##### `getSaml: Observable<ISamlResponse>`

###### Parameters

| Name                    | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `request: ISamlRequest` | The ISamlRequest object used for generating the SAML |
| `endpointUri: string`   | The endpoint used for generating the SAML            |

#### Models

##### ISamlRequest

| Name                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `redirectUrl: string` | The redirect URL used for generating the SAML (Audience and Destination nodes) |

##### ISamlResponse

| Name           | Description                             |
| -------------- | --------------------------------------- |
| `saml: string` | The base64 encoded SAML Response string |

### Abstract SAML Entry Service

#### Methods

##### `readValue: SsoGatewayModel`

###### Parameters

| Name              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `keyPath: string` | The key path for retrieving the data from the SAML redirect |

##### `deleteValue: void`

###### Parameters

| Name              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `keyPath: string` | The key path for retrieving the data from the SAML redirect |

### SsoGatewayEntryService extends AbstractSamlEntryService

The implementation utilizes local storage. Its up to the application to determine when to read the values and when to destroy the values.

#### Methods

##### `readValue: SsoGatewayModel`


###### Parameters

| Name              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `keyPath: string` | The key path for retrieving the data from the SAML redirect |

#### Models

##### SsoGatewayModel

| Name                                    | Description                                     |
| --------------------------------------- | ----------------------------------------------- |
| `Assertions: { [key: string]: string }` | The assertions that were read from the saml     |
| `Issuer: string`                        | The issuer from the SAML                        |
| `Audience: string`                      | The audience from the SAML                      |
| `Destination: string`                   | The Destination of the SAML                     |
| `Hash: string`                          | The data integrity hash                         |
| `KeyPath: string`                       | The Key Path suffix used for storing the values |