# Getting Started

Aspenware Identity is an OpenID and OAuth 2.0 application that can be accessed using any standard libraries designed to work with the OpenID Specification. You can authenticate using Aspenware Identity for your web application (client-side or server-side) or mobile app.

# Connecting With Javascript

Websites can authenticate with Aspenware Identity using client-side open ID connection libraries (OIDC). These JavaScript libraries can be configured to do many of the same authentication operations as server-side OIDC libraries. Depending on your needs, you can sign users in, retrieve user info (claims), and identify permitted scopes for the authenticated user. There are a number of OIDC libraries available for JavaScript including those designed for frameworks like VueJS, React or Angular.

# OIDC Client

OIDC Client JS (opens new window) is an excellent JavaScript library for interfacing with Aspenware Identity. It is a library to provide OpenID Connect (OIDC) and OAuth2 protocol support for client-side, browser-based JavaScript client applications. It also includes support for user session and access token management.

The OIDC client js library comes with two main classes that can be utilized depending on the level of integration you want to provide for your application. The UserManager class provides a high-level API for signing a user in, signing out, managing the user's claims returned from a successful sign-in, and managing the user's tokens. In addition to UserManager, this library provides low-level access to the OIDC/OAuth2 protocol using the OidcClient class.

UserManager requires a settings object as a parameter. The settings has the following properties:

authority (string): The URL of the OIDC/OAuth2 provider.
client_id (string): Your client application's identifier as registered with the OIDC/OAuth2 provider.
redirect_uri (string): The redirect URI of your client application to receive a response from the OIDC/OAuth2 provider.
response_type (string, default: 'id_token'): The type of response desired from the OIDC/OAuth2 provider.
scope (string, default: 'openid'): The scope being requested from the OIDC/OAuth2 provider.

Aspenware will provide the authority, Client ID and scopes when we work with you on the configuration of your application's access to Aspenware Identity. The redirect uri is the redirect address for your application upon successful authentication. The response type will be based on your desired connection to the library but a typical value would be 'code'.

For more info on getting started with JavaScript OIDC, see the documentation here (opens new window).

# Additional Resources

Vuex-Oidc (opens new window) is an excellent VueJS OIDC library that ties into the Vuex store and VueRouter for integration of authentication and works well with Aspenware Identity.
OIDC React Component (opens new window)
Angular 2 OAuth-2/OIDC library (opens new window)angular-oauth2-oidc#readme

# Connecting With .NET Core

After receiving a ClientId and, optionally, a ClientSecret, along with the URL to the IdentityServer, the process for connecting user authentication to your ASP.NET Core application is fairly straightforward.

# Connect an MVC Client (aspnetcore > 2.x)

Begin by creating a new ASP.NET Core MVC application. Add the NuGet package Microsoft.AspNetCore.Authentication.OpenIdConnect.

dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect

To add support for OpenID Connect authentication, add the following to the ConfigureServices method in the Startup class of your application.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    JwtSecurityTokenHandler.DefaultMapInboundClaims = false;

    services.AddAuthentication(options =>
        {
            options.DefaultScheme = "Cookies";
            options.DefaultChallengeScheme = "oidc";
        })
        .AddCookie("Cookies")
        .AddOpenIdConnect("oidc", options =>
        {
            options.Authority = "https://your.identity.server.com";
            options.ClientId = "mvc";
            options.ClientSecret = "secret";
            options.ResponseType = "code";
            options.SaveTokens = true;
        });
}

AddAuthentication adds the authentications services to the Dependency Injection container. A cookie is used to locally sign-in a user via the "Cookies" string as the DefaultScheme. Setting the DefaultChallengeScheme to "oidc" enables the OpenID Connect protocol.

Next, the AddCookie method adds the middleware handler that can process cookies.

Finally, AddOpenIdConnect is used to configure the handler that performs the OpenID Connect protocol. The configuration settings are as follows:

Authority - Indicates that your application is trusting Identity Server at the location specified.
ClientId - Enter the value provided from your Identity Server provider.
ClientSecret - (Optional) If provided, enter the client secret. The secret should be stored in a secure manner.
SaveTokens - Used to persist the tokens from Identity Server in the cookie to be used later.
ResponseType - Specifies that the "authorization code" flow with PKCE is used to connect to the OpenID connect provider. See here (opens new window) for more information.

In addition, JWT claim type mapping is disabled to allow well-known claims (e.g. "sub" and "idp") to flow through.

JwtSecurityTokenHandler.DefaultMapInboundClaims = false;

To ensure the authentication services execute on each request, add UseAuthentication to the Configure method in Startup.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseStaticFiles();

    app.UseRouting();
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

The final step is to trigger the authentication handshake. To enable that, go to the controller action that you wish to secure and add the [Authorize] attribute. Run the application and navigate to the controller action decorated with the [Authorize] attribute. A redirect attempt should be made to the Identity Server. Once the user successfully logs in, the Identity Server should redirect back to the MVC application. In order for this to work, you must provide your application url(s) to the Identity Server provider.

# Connect an MVC Client (aspnetcore 2.x)

Begin by creating a new ASP.NET Core MVC application. Add the NuGet package Microsoft.AspNetCore.Authentication.OpenIdConnect.

Install-Package Microsoft.AspNetCore.Authentication.OpenIdConnect -Version 2.2.0

To add support for OpenID Connect authentication, add the following to the ConfigureServices method in the Startup class of your application.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();

    services.AddAuthentication(options =>
        {
            options.DefaultScheme = "Cookies";
            options.DefaultChallengeScheme = "oidc";
        })
        .AddCookie("Cookies")
        .AddOpenIdConnect("oidc", options =>
        {
            options.Authority = "https://your.identity.server.com";
            options.RequireHttpsMetadata = true;
            options.ClientId = "mvc";
            options.ClientSecret = "secret";
            options.SaveTokens = true;
        });
}

Next, the AddCookie method adds the middleware handler that can process cookies.

Finally, AddOpenIdConnect is used to configure the handler that performs the OpenID Connect protocol. The configuration settings are as follows:

Authority - Indicates that your application is trusting Identity Server at the location specified.
RequireHttpsMetadata - Indicates whether the Authority address requires HTTPS. This should be set to true in a production environment.
ClientId - Enter the value provided from your Identity Server provider.
ClientSecret - (Optional) If provided, enter the client secret. The secret should be stored in a secure manner.
SaveTokens - Used to persist the tokens from Identity Server in the cookie to be used later.

In addition, JWT claim type mapping is disabled to allow well-known claims (e.g. "sub" and "idp") to flow through.

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();

To ensure the authentication services execute on each request, add UseAuthentication to the Configure method in Startup.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseAuthentication();

    app.UseStaticFiles();
    app.UseMvcWithDefaultRoute();
}

Be sure to add the UseAuthentication before the MVC in the pipeline.

# Connecting With Mobile Apps

Developers can connect Mobile Applications to Aspenware Identity to authenticate users and gather profile information about the authenticated user. We recommend using AppAuth to easily authenticate Mobile apps to Identity. AppAuth is an authentication library created by the OpenID Foundation that supports Javascript/node.js, iOS, Android, and other platforms. This library faithfully adheres to the OpenID specification.

# AppAuth

AppAuth is a client SDK for native apps to authenticate and authorize end-users using OAuth 2.0 and OpenID Connect. As outlined in the documentation, AppAuth "strives to directly map the requests and responses of those specifications, while following the idiomatic style of the implementation language. In addition to mapping the raw protocol flows, convenience methods are available to assist with common tasks like performing an action with fresh tokens."

To connect your implementation of AppAuth to Aspenware Identity, you will set a configuration object as follows:

{
  "client_id": "<your client ID issued by Aspenware",
  "redirect_uri": "<your app URI>:/authredirect",
  "authorization_scope": "api1 openid profile",
  "discovery_uri": "<Aspenware-provided authority URL>/.well-known/openid-configuration",
  "authorization_endpoint_uri": "",
  "token_endpoint_uri": "",
  "registration_endpoint_uri": "",
  "user_info_endpoint_uri": "",
  "https_required": true
}

Aspenware Identity is specifically setup for the Resource Owner Password Credential (ROPC) flow. We recommend starting with sample apps that illustrate connecting to Identity using AppAuth:

To get the sample app to connect to Aspenware Identity, you'll want to make changes to LoginActivity, TokenActivity, and the auth_config.json. Use the example in the active-directory-b2c sample to get it working:

Convert AppAuth to work with the Resource Owner Password Credential flow (opens new window)

← Identity Overview Troubleshooting →