OpenID Connect SSO overview
OpenID Connect (OIDC) is an OAuth 2.0-based authentication protocol that's been adopted by major technology companies.
Basic SSO
Regardless of the feature choices you’ve selected, the setup requirements of basic SSO are the same. Adding loyalty or credit card implementations will require additional information.
Setup requirements
To properly set up the OIDC SSO access to your template site, we need a few things, including:
- APIs (authorize, token, userProfile)
- ClientId
- Client secret
- ResponseMode
- isNounceEnabled
- customerDetailsAPIKey (if available)
A standard OIDC SSO implementation at Expedia will be encrypted using our public key, create a post-authorization endpoint, enable nounce, and set scope parameters. We’ll also include user information.
Authorization
The GET /authorize endpoint is used for authentication and authorization. It returns an authorization grant to the client.
Request parameters
| Parameter | Description | Data type | Sample value | Mandatory? |
|---|---|---|---|---|
client_id | Identifies the client. Must match the value preregistered in your identity provider (IDP). Obtained during either manual client registration or via the Dynamic Client Registration API. | String | Yes | |
nonce | Used to mitigate replay attacks. This value is returned in the ID token. | String | Yes | |
prompt | The type of interaction required to validate. | String | Valid values: none consent | No |
redirect_uri | Callback location where the authorization code or tokens should be sent. Must match the value preregistered in your IDP during client registration. | String | Yes | |
response_type | code (IDP) value. | String | Yes | |
response_mode | How the authorization response should be returned. | String | Valid value: query | No |
scope | Access token, used for fetching profile details. Required for authentication requests. | String | OpenID, profile, and email | Yes |
state | The state of the interaction. This value is returned in the token, and enables the user to click through, authenticate, and be returned to the page they’re originally interested in. The value can contain alphanumeric, comma, period, underscore, and hyphen characters. | String | Yes |
Response parameters
| Parameter | Description | Data type | Mandatory? |
|---|---|---|---|
code | Authorization code that identifies the client. This must match the value preregistered in your IDP. Obtained during either manual client registration or via the Dynamic Client Registration API. | String | Yes |
state | The state of the interaction. This value is returned in the token, and enables the user to click through, authenticate, and be returned to the page they’re originally interested in. The value can contain alphanumeric, comma, period, underscore, and hyphen characters. | String | Yes |
Tokens
The POST /token endpoint is used to verify the user’s identity by presenting an authorization grant.
Request parameters
| Parameter | Description | Data type | Mandatory? |
|---|---|---|---|
grant_type | The mechanism an IDP uses to authorize the creation of the tokens. Value: authorization_code | String | Yes |
redirect_uri | Specifies the callback location where the authorization was sent. This value must match the redirect_uri used to generate the original authorization_code or the token endpoint will fail. | String | Yes |
code | Client identification code received in /authorize call response. | String | Yes |
Request headers
| Field | Description | Data type | Sample value | Mandatory? |
|---|---|---|---|---|
accept | Must be "application/json" | String | application/json | Yes |
authorization | Encodes the client ID and secret with Base64. Use the encoded information in the HTTP authorization header. | String | Basic<Base64 encoded client ID and secret> | Yes |
Content-Type | Must be "application/x-www-form-urlencoded" | String | application/x-www-form-urlencoded | Yes |
Response parameters
| Field | Description | Data type |
|---|---|---|
access_token | An access token | String |
token_type | The audience of the token | String |
expires_in | The expiration time of the access token in seconds | Integer |
scope | The scopes contained in the access token | String |
id_token | An identifier that’s returned if the OpenID scope is granted | String |
ID_token is a JSON Web Token (JWT) that includes pieces of authentication information called claims. Expedia template solutions use the claims header, payload, and signature as in the table below.
Header claims
| Field | Description | Data type | Mandatory? |
|---|---|---|---|
alg | Identifies the digital signature algorithm used (always RS256) | String | No |
kid | Key ID: Identifies the public key used to verify the ID token; the corresponding public key can be found via the JSON Web Key Set (JWKS) | String | Yes |
Payload claims
| Field | Description | Data type | Mandatory? |
|---|---|---|---|
amr | JSON array of strings that are identifiers for authentication methods | Array | No |
aud | Identifies the audience that this ID token is intended for (one of your application's OAuth 2.0 client IDs) | String | Yes |
auth_time | The time the end user was authenticated, represented in Unix time (seconds) | Integer | No |
exp | The time the ID token expires, represented in Unix time (seconds) | Integer | Yes |
iat | The time the ID token was issued, represented in Unix time (seconds) | Integer | No |
idp | An indicator of the identity provider | String | Yes |
iss | The URL of the authorization server that issued this ID token | String | No |
jti | A unique identifier for this ID token for debugging and revocation purposes | String | Yes |
sub | A unique identifier for the subject of the authorization call (the user) | String | No |
ver | The semantic version of the ID token | Integer | Yes |
Signature claims
Signature validation: The signature will be validated against the appropriate key for that client_id and algorithm.
Add loyalty
As part of your template site, you can include the ability for your customers to earn loyalty points on their travel purchases. If you choose, your template can also allow your customers to use their accumulated loyalty points to purchase travel.
The same setup requirements as the standard implementation apply, as do many of the values. Only those that are different are included here.
In addition to the standard user information, the loyalty program setup will include the following values.
programAccount
| Field | Description | Mandatory? |
|---|---|---|
programId | Identifier for the loyalty program the customer is affiliated to or the tier name associated with the loyalty program | Yes |
loyaltyAccountNumber | The customer’s loyalty account number; should only be populated if a secondary identifier (other than the unique membershipId) is required for loyalty operations | No |
lastFourDigitsOfCreditCard | The last 4 digits of the credit card the customer used for the booking | No |
accountName | Program name (if different from tier name) | No |
loyaltyConversionRatio | Ratio of how payment converts to points earned (for example, $1 = 1 point) | No |
loyaltyAccountBalance | Current balance of customer’s earned loyalty points | Yes |
value | Loyalty balance; nested under loyaltyAccountBalance | Yes |
currency | The earn currency used by the loyalty program, for example, CAD, USD, POINTS, MILES; nested under loyaltyAccountBalance | Yes |
Restrict payment card
We can set your site up so that your customers must use your organization’s credit card to book. This is optional, as all of the template solutions can accept all major credit or debit cards and (in the US) PayPal.
Credit card safety and storage
If you choose to require purchase using your organization’s custom credit card, we want you to feel secure. Here’s how we handle that.
- Card information is stored in a tokenized form that’s linked to the customer's Expedia profile. It is never stored unencrypted.
- No human beings have access to unencrypted card data, and decryption only happens with secure IAM credentials.
- When a card is preloaded to the checkout page, only the card description is visible, not the card number.
- The customer must enter the card’s CVV to complete the booking with the stored card.
Setup requirements
In addition to the setup requirements from the standard implementation, adding your credit card means we’ll need:
- An endpoint to use for the AuthnRequest parameter.
- Your public key for signature verification.
We’ll use Expedia’s private key to sign the AuthnRequest payload and our public key to provide signature validation to your end.
Payload details
Along with the attributes described in the standard implementation, when a customer logs in on your site, credit card SSO initiates to send two transaction parameters to the secure Expedia SSO endpoint:
- user info API: Encoded and signed response payload with signed and encrypted assertions.
- RelayState: A deep link to the landing page URL.
Note
If your template site is also set up to earn loyalty points, you’ll also need the programAccount information.
The payload will also contain the following credit card details:
| Field | Description | Mandatory? |
|---|---|---|
cardNumber | The card number to be charged | Yes |
cardType | Type of card used (for example, Visa, MasterCard, American Express) | Yes |
expirationDate | Expiration date of the card used | Yes |
BillingAddress | Billing address associated with the card used | Yes |
addressCategoryCode | The type of address to be billed, for example, home or office; nested under BillingAddress | Yes |
firstAddressLine | First line of the billing address; nested under BillingAddress | Yes |
secondAddressLine | Second line of the billing address; nested under BillingAddress | No |
thirdAddressLine | Third line of the billing address; nested under BillingAddress | No |
cityName | City of the billing address; nested under BillingAddress | Yes |
provinceName | Province of the billing address; nested under BillingAddress | Yes |
postalCode | Postal code of the billing address; nested under BillingAddress | Yes |
countryCode | Country code of the billing address; nested under BillingAddress | Yes |