Reference13r3:Concept OAuth2 Windows Authentication

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.

Login with windows password in myApps

The login process using windows credentials:

• myApps opens the authorization URL of your OpenID server inside an IFrame
• 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

Session key

As OAuth2 doesn't offer a session key, a secure session key is generated through the client and PBX websocket connection using ECDH.

Temporary credentials

The PBX creates temporary credentials for the login and stores them at the user object. After that it encrypts the credentials using the ECDH session key and sends them to the web application.

Login

For the actual login, myApps uses the temporary credentials. When the user logs out the credentials are deleted both in the PBX and the Browser.

Characteristics

• The windows password is just used inside the OpenID authorization IFrame. It is never stored or transmitted over the network to the PBX or event the client itself.
• The temporary credentials are stored in the PBX at the user object and the DOM storage of the browser. So the user doesn't have to enter the windows password again, if the PBX or the browser is restarted.
• On logout the temporary credentials are deleted in the DOM Storage of the browser and in the PBX. So the next time the user is asked again for the windows password.

Requirements

OpenID server

• You must have an OpenID compliant server. For windows, this is AD FS.
• An OpenID server 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 unique-name claim
  • support for none claim
  • at least one key which is used for token signing

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 (samAccountName).
• 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 ADFS 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

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

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 your have a Token-signing certificate

There are also Powershell commands to add server applications etc., but they are out of scope of this article.

PBX

• Configure the Oauth2 service on the innovaphone device on page Services/OAuth2/Config.
• Activate OAuth2 authentication on page PBX/Config/Authentication

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.

Tracing and logging

You can enable tracing on the "OAuth2 module" and "HTTP Client" at Maintenance/Diagnostics/Tracing to see issues with fetching of the OpenID configuration or id_token parsing and the HTTPS connection. Additionally, you can enable "Browser Console" at myAPPS client trace options and obtain myAPPS trace to see what's happening on the client side.

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.