Reference13r3:Concept OAuth2 Windows Authentication

From innovaphone wiki
Jump to navigation Jump to search


Users can login-in to myApps using their windows password. The PBX uses OAuth2 with an OpenID configuration to verify the login information.

Applies to

  • innovaphone devices with a PBX from version 13r3
  • innovaphone myApps (all platforms)

How it works

Connection to the OpenID server

The OAuth2 service of the PBX retrieves the OpenID configuration from the configured OpenID server.
This configuration is used to generate an authorization URL and to verify the login information which is retrieved after the login.

MyApps OAuth2 flow config.png

Login with windows password in myApps

The login process using windows credentials:

  • myApps starts the login and learns that OpenID is configured
  • If the user selects OpenID for authentication, myApps opens the authorization URL of your OpenID server inside a popup window.
  • after a successfull login with the windows credentials, the OpenID server redirects back to the Redirect URI of the PBX
  • the redirect contains an id_token which itself contains the login information
  • the signature of the id_token is verified against the OpenID configuration to ensure that the login is from the correct OpenID server
  • the myApps login is completed

MyApps OAuth2 flow login.png

Shared secret

OAuth2 doesn't offer a shared secret and the user's password is unknown by the PBX and myApps. So we do an ECDHE key agreement to create a shared secret that is used for digest calculations and encryption of session parameters.

Session credentials

The PBX creates session credentials for future connections and stores them at the user object. After that it encrypts the credentials using the shared secret and sends them to the web application.

Login

For the initial login, the username from the id_token and the shared secret is used. For subsequent connections, the session credentials are used.

Note: If the user is already logged-in at the OpenID provider, the redirect to the Redirect URL is done without asking for credentials and the login is completed automatically.

Logout

If the user actively logs out, the session credentials are deleted in the PBX and on the myApps client. So for the next authentication, the login screen is displayed again.

Note: Logging out from myApps does not mean a logging out from the OpenID provider.

Characteristics

  • The windows password is just used inside the OpenID authorization page. It is unknown by the PBX and the myApps client and it is never stored or transmitted over the network.
  • During the login, a shared secret is negotiated using an ECDHE handshake. Session credentials are created and stored in the PBX at the user object and the DOM storage of the browser. So the user doesn't have to authenticate again, if the PBX or the browser is restarted.
  • On logout the session credentials are deleted in the DOM Storage of the browser and in the PBX. So the next time the user is asked again for authentication.

Requirements

OpenID server

We have developed and tested the functionality based on Microsoft Active Directory Federation Service (AD FS):

  • Windows Server 2022 has been successfully tested
  • Windows Server 2019 has been successfully tested
  • Windows Server 2016 has been successfully tested
  • Windows Server 2012 is not supported
  • Microsoft Azure AD has been successfully tested (13r3 SR2 onwards)

In principle, any server that meets the following conditions should work

  • OpenID compliant server
  • It has a well-known configuration URI, e.g. https://adfs.domain.com/adfs/.well-known/openid-configuration
  • The OpenID configuration must deliver:
    • Authorization endpoint
    • JWKS URI
    • support for id_token response type
    • support for id_token signing algorithm RS256
    • support for response mode form_post
    • support for upn claim
    • support for nonce claim (optionally, but the random client nonce must be still echoed inside the ID token)
    • at least one key which is used for token signing

However, as we have not carried out tests with other OpenID server variants, use with such servers is not supported.

PBX

  • Firmware from version 13r3 or later.
  • Working DNS configuration.
  • The usernames (Name) of the user objects in the PBX must match the Windows usernames which are sent within the id_token (normally the upn field in AD FS).
  • OAuth2 authentication must be enabled on the PBX/Config/Authentication page in the advanced UI.

RP/Firewalls

  • all communication is done via HTTPs
  • RPs/Firewalls must allow access to the AD FS authorization URL (with can be retrieved by looking at the response of the openid configuration URL)
  • RPs/Firewalls must allow access to the OAuth2 module on the PBX which is accessed by the myApps clients, e.g. https://pbx.domain.com/OAUTH2/oauth2_login.htm
  • the PBX must be able to access the OpenID configuration URL

Configuration Microsoft AD FS

This just describes the configuration on a Windows 2019 server, but every OpenID server meeting the above mentioned requirements should be possible to use.

Activate AD FS server role

  • make sure the AD FS server role is activated in your Windows Server

Server application with Client-ID

  • open your AD FS management
  • go to Application groups
  • add a new Application group
  • select Server application
  • give it a name of your choice and proceed
  • note down the Client-ID
  • add the Redirect URI of your PBX, e.g. https://pbx.domain.com:443/OAUTH2/oauth2_login.htm
    • here you can also add multiple Redirect URIs for all your slaves and standbys too
  • generate a secret key (this key isn't used inside the PBX, so you don't need to note it)

Token signature certificate

  • open your AD FS management
  • go to Service
  • go to Certificates
  • ensure you have a Token-signing certificate
There are also Powershell commands to add server applications etc., but they are out of scope of this article.

Configuration Microsoft Azure AD

Support has been added in 13r3 SR2.
Login to your Microsoft Azure portal, e.g. on https://portal.azure.com and Manage Azure Active Directory.

Add App Registration

  • click on + Add and select App Registration
  • enter any name
  • select suitable supported account types according to your usage
  • Redirect URI: select Web as platform and add the Redirect URI of your PBX, e.g. https://pbx.domain.com:443/OAUTH2/oauth2_login.htm
    • here you can also add multiple Redirect URIs for all your slaves and standbys too
  • click Register to add this App Registration

Authentication

  • open the Authentication page of this new App Registration
  • tick ID tokens (used for implicit and hybrid flows) so that the ID token is sent to the PBX on a successfull login
  • save

Token Configuration

  • open the Token Configuration page
  • click + add optional claim
  • select ID as token type
  • tick email in the list of available claims
  • click Add and a second time Add (no need to tick the additional questioned checkbox)

Overview

Configuration PBX

On all PBXes in the system:

Usage

Depending on the configuration on page PBX/Config/Authentication users can use their PBX user password, their Windows password or both for the myApps login.

OAuth2 only
Shows a button redirecting to the OpenID provider.
PBX only
Shows a login form with fields for username and password.
PBX and OAuth2
Shows both and lets the user decide.

Tracing and logging

The following trace flags can be activated at Maintenance/Diagnostics/Tracing.

OAuth2
fetching the OpenID configuration
processing of incoming id_tokens
communication between the OAuth2 module and the PBX
PBX
communication between the PBX and the myApps client
HTTP Client
the HTTPS communication for fetching the OpenID configuration


Additionally, you can enable the following trace flags at the myApps client.

Browser Console
login-flow and possible errors from the client perspective

Alarms and Events

  • an event is generated on every id_token which cannot be parsed or verified
  • an alarm is generated if the Open ID configuration cannot be fetched or is invalid

Test page

You can also use the test page at Services/OAuth2/Test.

id_token

The OpenID server redirects to the PBX after a successfull login. This redirect contains two form variables:

  • id_token
  • state: this is just echoed from the initial authorization URL to be able to link the login in myApps to the id_token

An id_token is a JSON Web Token in the following format:

base64url(JSON header).base64url(JSON payload).base64url(binary signature)

decoded header example

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "VtIJQ2e2n7_Nmui0Bk7veW5IUPQ",
  "kid": "VtIJQ2e2n7_Nmui0Bk7veW5IUPQ"
}

decoded payload example

{
  "aud": "8e4e2791-8583-4141-ce5b-a16f048758d9",
  "iss": "https://adfs.domain.com/adfs",
  "iat": 1663142781,
  "nbf": 1663142781,
  "exp": 1663146381,
  "auth_time": 1663138217,
  "nonce": "123456",
  "sub": "wtj0QFR+Y2vsjTJXCclEZ4vtQKIEZKIOSpPRvxxLIxY=",
  "upn": "username@domain.com",
  "unique_name": "DOMAIN\\username",
  "sid": "S-1-5-11-864245398-616249376-725345543-3105"
}

signature

The signature is binary. The signature is verified by calculating the SHA256 hash of "base64url(header).base64url(payload)" and generation of an RSA public key of the n and e properties of the OpenID key with the kid retrieved inside the header JSON. With this rsa key and the hash the binary signature is verified.

Retrieved from "https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_OAuth2_Windows_Authentication&oldid=71321"