---
title: "Basics"
canonical: "https://docs.pbs.org/space/PMSSO/51052564/Basics"
format: markdown
---
> Macro (toc)

## Session Management 

A session is an authenticated state that begins when users log in to a web or mobile application and ends when they log out, or after expiration.  

From the perspective of the end user, a session refers to an authenticated state that is established after logging into a web or mobile application. This session remains active until the user logs out or the session expires. Throughout this duration, users can access various components of the application's user interface, including their account details, which would otherwise be inaccessible. 

From the application's perspective, a session is a storage of user-specific data that is necessary for providing a customized and secure experience. This includes information that identifies the user, their authentication status, and other pertinent details. 

Public Media SSO uses the OpenID Connect (OIDC) Protocol and OAuth 2.0 Authorization Framework to authenticate users. We ***do not recommend*** creating a session management from scratch. Most web development frameworks come with built-in session management features, and many [OIDC (OpenID Connect) libraries](https://docs.pbs.org/space/PMSSO/28901394/Developer+Guide#Libraries) include session management. Some OIDC libraries also allow you to use your preferred session library.  

### Types of Sessions  

| **Type of Session** | **Description** |
| --- | --- |
| **Application Session** | Session information maintained by the web or mobile application with which the user is interacting. Includes the user’s identity received from Hosted Login. |
| **Hosted Login Session** | Hosted Login creates and saves a session for each user that contains details about the time and method of authentication. The session is established using a first-party session cookie and is tied to the user’s device and browser. The session expires automatically after 90 days of inactivity. |
| **IdP (Identity Provider) Session** | When a user logs into an application using their Facebook, Apple or Google account, the application checks for a valid session with the identity provider (IdP). The IdP owns and handles this session, which is separate and independent from the Hosted Login Session. This session can share identity information with the application. |

## Tokens 

Login is a crucial aspect of session management. It offers a set of functional tokens that can be stored in the application's session, in exchange for proof of the user's identity and authentication. These tokens include the Access Token, Refresh Token, and Identity Token. 

There are** four primary token types** when working with OIDC and Hosted Login: 

| **Type of Token** | **Description** |
| --- | --- |
| **Access Token** | A credential, often in the form of a string, issued by an authentication server. This token signifies that the user has been authenticated and grants the user access to resources or services for a limited period of time. Access tokens are valid for a limited period. Once the token expires, the user must re-authenticate or refresh the token to continue accessing the resources.  
Access Token Lifespan: 1 hour |
| **Refresh Token** | A special kind of token, used in the authentication process, that allows an application to obtain a new access token without requiring the user to re-authenticate. In Single Sign-On (SSO) context, refresh tokens play a crucial role in maintaining seamless user sessions across multiple applications or services.  
Refresh Token Lifespan: 90 days |
| **Identity Token** | Contains details about the user’s authentication information. The token may also include data about the user, such as their name or email address, but it is not mandatory. |
| **Anti-forgery State Token** | Also known as Cross-Site Request Forgery (CSRF) tokens, these are unique and randomized values that need to be included in your server’s authentication request and sent as part of OAuth 2.0 or OpenID Connect authentication requests. These tokens are different from other OIDC tokens in that they are not generated by the server. Instead, you need to create the token yourself and include it in your authentication request. These tokens play a crucial role in preventing CSRF attacks. |

## Login Flow

![sso-login-flow.jpg](media://a4413e3e-fb6e-40a2-b32e-3b82cd316d7c)

The following steps demonstrate how session management works and Public Media SSO's role in it. 

1. When an end user clicks a login or registration action element on a site or app (e.g., a login button), a call must be made to the /login/authorize endpoint to display the ​Akamai​-hosted login page to the user. The end user is redirected to the Akamai (OpenID Provider) and must complete authentication before they are sent back to the app.

```
https://{hostname}/{customerId}/login/authorize 
?client_id={client_id} 
&redirect_uri={redirect_uri} 
&scope=openid 
&code_challenge={code_challenge} 
&code_challenge_method=S256 
&response_type=code 
&claims={"userinfo":{"given_name":null}} 
&state={state_value} 
```

2. The user is granted an authorization code and redirected back to the app’s redirect_uri.
3. The app then makes a request to the /token endpoint to exchange the authorization code for a set of tokens (ID token, access token, refresh token).

```
curl -X POST \ 
https://{hostname}/{customerId}/login/token \ 
-d 'grant_type=authorization_code' \ 
-d 'code={authorization_code}' \ 
-d 'redirect_uri={redirect_uri}' \ 
-d 'client_id={client_id}' \ 
-d 'code_verifier={code_verifier}' 
```

4. Upon receiving the ID token, the application must validate the `id_token` and can then use the `access_token` to retrieve user information or perform authorized actions on behalf of the user.

**Decoding ID Token**

```
json 
 { 
"at_hash": "value", 
"aud": ["client_id"], 
"auth_time": timestamp, 
"exp": expiration_time, 
"iat": issued_at_time, 
"iss": "issuer", 
"sub": "subject_identifier" 
} 
```

5. Depending on the scopes and claims included in the authentication request, the application gets back information from the user profile at the same time the tokens are issued. If additional user data is required, the application can call the /userinfo endpoint.

**User Info Request Example**

```
curl -X GET \ 
https://{hostname}/{customerId}/profiles/oidc/userinfo \ 
-H 'Authorization: Bearer {access_token}' 
```

## Logout

When a user initiates a logout from the application, or when their session expires, the application must take the following actions: 

- Revoke the tokens provided by Hosted Login
- End the application session

**Revoke Hosted Login Tokens**

To revoke Hosted Login tokens, the application should make a POST request to the `/login/token/revoke` endpoint with the access_token stored in the application session. The following command demonstrates the procedure: 

```
curl -X POST \ 
 https://{hostname}/{customerId}/login/token/revoke \ 
 -d 'token=HnsFZz0ZZuSK26Yx8NcPCqc-3xzBkKgwyw09b9-NdVbEARDn-O1KGlxh3iUE__LL' \ 
 -d 'token_type_hint=access_token' \ 
 -d 'client_id=12a345b6-c7d8-9e01-f2g3-h4567i890j12' 
```

This action renders the token invalid, preventing further access to resources. 

**End Application Session**

The application should also ensure the complete termination of the user's session within the application environment. Since Hosted Login cannot directly terminate application sessions, the application needs to handle the termination of other application sessions based on its session management architecture. 

**Profile Screen Logout**

Public Media SSO also provides profile management screens with a built-in Log Out button. Clicking this button ends the Hosted Login session.  

![sso-sign-out.jpg](media://2da88587-1fa7-4bff-bac3-72bc0d2619a6)

**End Login Session**

To end the Hosted Login session when a user logs out of the application, make a redirect to the **/auth-ui/logout** endpoint.

```
https://{hostname}/{customerId}/auth-ui/logout
	?client_id=12a345b6-c7d8-9e01-f2g3-h4567i890j12
	&redirect_uri=https://myapp.com/logout
```

This will end the Hosted Login session and place the user at the provided `redirect_uri`.

Ending the user’s application and Hosted Login sessions may be all that’s needed for your use case. However, if you have multiple application sessions and you’d like to ensure they’ve all been ended, you’ll need to take additional steps.

## Single Sign-On (SSO)

Single Sign-On (SSO) is a feature of Public Media SSO that enhances user convenience and streamlines authentication processes across multiple applications. It allows end-users to authenticate once with one organization's application, and access other applications without the need for another authentication. Public Media applications that seamlessly integrate this SSO functionality provide a cohesive and user-friendly experience.   

In order for SSO to work:

1. Applications must use the same login domain ([publicmediasignin.org](http://publicmediasignin.org/))
2. Users must access the application on the same device or browser.

**How it works**

The following steps outline the general process after the user clicks the login button: 

- The end-user navigates to the web or mobile application.
- The application checks for an active session.

**If no active session: **

- Login sign-in screen displays for authentication.
- Upon authentication, the user is redirected back to the application with an authorization code.

**If an active session exists: **

- If the user is accessing the application for the first time, the user is directed to accept the organizations *Privacy policy* and *Terms of Use*.
- If the user has already accessed the application, the user is redirected back to the application.
- The application creates or updates the user’s session as required.

## Authentication vs Authorization 

In the context of SSO systems, it's important to understand the difference between authentication and authorization. Authentication verifies the identities of users, while authorization controls the user’s actions within a system. SSO is responsible only for authenticating the user's identity. Each Service Recipient is independently responsible for providing authorization. 

**Authentication** is the initial phase in the SSO process, serving as the gatekeeper to verify the identity of users. It validates whether individuals are who they claim to be. Think of it as the first line of defense, ensuring only legitimate users gain entry into the system. 

**Authorization **comes into play after a successful authentication. Once a user's identity is confirmed, authorization determines the specific resources, functionalities, or data they are permitted to access within the system. For instance, after a user successfully authenticates, [PBS Membership Vault](https://docs.pbs.org/space/PLUS/5505026/Membership+Vault) dictates if the user should be be granted access to Passport. 

## Data Sharing and Compliance

Federated identity management is a process that allows users to access multiple applications and services using a single set of credentials. This is made possible by a central Identity Provider (IdP), such as Akamai, which authenticates users and issues identity tokens. The user's information is stored in the central Akamai database, and access to the data is granted based on user authentication. Akamai uses standards like OAuth and OpenID Connect to ensure secure and streamlined authentication across different organizations and platforms. 

**Benefits**

- **Improved User Experience** - Users can access multiple services seamlessly without the need to manage multiple sets of credentials.
- **Privacy** - Enhanced control over personal data across organizations.
- **Single Sign-On (SSO)** - Simplified user experience by logging in once and access various services across organizations.
- **Reduced Costs** - Centralized management reduces the administrative burden and lowers resource requirements.
- **Improved Compliance** - Helps organizations adhere to regulatory standards through secure and centralized user management.

**Process**

The process of identity federation involves several key steps: 

1. **User Authentication** - Users log in via the central identity provider, Akamai.
2. **User Control and Consent** - Users grant permission to share data by accepting the organization's privacy policy and terms of use upon first access.
3. **Token Issuance** - Akamai issues an identity token upon successful authentication.
4. **Service Access** - The organization verifies the scope of access against user-granted permissions.

**Account Types**

Data sharing within the context of SSO varies based on the user's authentication to individual organization. 

Account types include: 

- Service Recipient-only account (e.g., PBS-only, NPR-only, station-only account)
- Combined accounts (PBS and NPR, PBS and Station, NPR and Station, or PBS, NPR, and Station)

Data sharing and access are granted during the authentication process. For example, if a user has authenticated with KQED, no other organization can access that user’s information until and unless the user authenticates with the specific organization. The following table breaks down the access to user information based on single Service Recipient-only account and combined accounts (e.g., NPR and Station account). 

**Service Recipient-Only Account (e.g., Station-Only)** 

|  |  |  |  |
| --- | --- | --- | --- |
| ** ** | **PBS ** | **NPR ** | **Station ** |
| Akamai user profile is created/associated with public media login client | ⛔ | ⛔ | :check_mark: |
| Customer Care agent can access, view, and update the profile from the Akamai Customer Care portal | :check_mark:***** | ⛔ | :check_mark: |
| The user information is synced with the organizations internal systems (e.g., CRMs, marketing platforms) | ⛔ | ⛔ | :check_mark: |
| Passwords are synced with internal systems | ⛔ | ⛔ | ⛔ |
| Users can delete their account, and relevant account information it deleted from Akamai and the organization’s internal systems. | ⛔ | ⛔ | :check_mark: |

** Combined Account (e.g., NPR-account & Station-account) **

|  |  |  |  |
| --- | --- | --- | --- |
| ** ** | **PBS ** | **NPR ** | **Station ** |
| Akamai user profile is created/associated with public media login client | ⛔ | :check_mark: | :check_mark: |
| Customer Care agent can access, view, and update the profile from the Akamai Customer Care portal | :check_mark:*** ** | :check_mark: | :check_mark: |
| The user information is synced with the organizations internal systems (e.g., CRMs, marketing platforms) | ⛔ | :check_mark: | :check_mark: |
| Passwords are synced with internal systems | ⛔ | ⛔ | ⛔ |
| Users can delete their account, and relevant account information it deleted from Akamai and the organization’s internal systems. | ⛔ | :check_mark: | :check_mark: |

> 📝 *As the service provider, PBS can access all data within the Akamai database. However, access to this data is for operational purposes only, unless the user authenticates with PBS.  *

**Compliance** 

The Akamai platform facilitates compliance with applicable laws and regulations by offering individuals rights over their data, including the right to access and delete their information. Organizations using SSO must ensure they comply with their specific data protection and privacy laws to maintain the integrity and privacy of user data.  

For example, if a user requests their account information be deleted, PBS notifies the service recipient. It is the organization's responsibility to complete the deletion request from their own databases. See the [Account Deletion](https://docs.pbs.org/space/PMSSO/50364479/Technical+Configurations#Account-Deletion-Notifications), [Terms of Use](https://docs.pbs.org/space/PMSSO/4111927/Service+Recipient+Terms+of+Use), and [Data Protection Addendum](https://docs.pbs.org/space/PMSSO/4111920/Data+Protection+Addendum) for more information. 

## Authorization Request Reference 

**Required Authorization Values  **

- **OpenID Connect URL:** Your base URL for calling Hosted Login from your site or app. For example, when a user clicks a “Log In” button on your web page, Hosted Login is called to display the Sign In screen with this URL.
- **Public OIDC Client ID**: Used to implement Hosted Login on your site or app with a library or plugin that does not require a client secret. Each
- **Customer ID**: The unique identifier for your Hosted Login instance. You’ll reference this when integrating it with your site or app.
- **Profile URL**: Your URL for calling the Hosted Login profile screen from your site or app. This is the screen that allows the end user to view and edit their profile. For example, when an authenticated user clicks a “My Profile” button on your web page, Hosted Login is called with this URL to display the profile screen.

**Optional Authorization Parameters**  

- **Response Type**: As a best practice, Hosted Login supports the Authorization Code grant. With this grant type, the authorization endpoint returns a unique one-time code to your site or application. This code can then be exchanged for an access token, a refresh token, and an identity token.
  - **Value: **code` `
- **Scope**: The scope parameter is used to specify what user information you’d like to retrieve immediately when a user logs in. You can request more than one scope in this parameter. The following Scopes are supported by Public Media SSO Hosted Login:
  - **openid: **Identifies your request as an OIDC request. This scope must be included in all your authentication requests.
  - **profile: **Requests access to the following attributes (note that these are OIDC attribute names and not ​Akamai​ Identity Cloud attribute names):
    - name
    - family_name**:** User’s last name.
    - given_name
    - updated_at
  - **email**: Requests access to the following attributes:
    - email
    - email_verified
- **Claims:** Allows you specify an individual claim (or set of claims) as part of your authentication request. Public Media SSO Hosted Login supports the following OpenID Connect claims:
  - **sub: **Unique identifier for the user. For Hosted Login, the sub is the user’s Hosted Login UUID (Universally Unique Identifier).
  - **iss: **URL of your Hosted Login login page.
  - **auth_time: **Date and time that the user was last authenticated.
  - **given_name: **User’s first name.
  - **family_name**: User’s last name.
  - **updated_at**: Date and time that the user’s user profile was last updated.
  - **email**: User’s email address.
  - **email_verified**: Date and time that the user’s email address was verified.` `
- **Prompt: **Specifies which screen (if any) is displayed when a user makes an authorization request. Allowed values are:
  - none: Hosted Login will look for an existing valid session and, if found, the user is automatically authenticated and can seamlessly continue. If a valid session is NOT found, instead of prompting the user to sign in, a login_required error is returned. In other words, this option suppresses the display of Hosted Login screens to the user.
    - **Scenario: **You want to provide a hidden Single Sign-On (SSO) experience to your end users when they navigate between your sites. In this case, call Hosted Login with *prompt=none *to secretly check for a valid Hosted Login session when they navigate to one of your sites. If a valid session is found, they are automatically logged in. If a valid session is NOT found, they need to sign in as they normally would.
  - **login: **The user will be prompted to sign in, regardless of having an existing session from a previous login or not. This option is better suited where it’s most important to you to increase security around the action being taken.
    - **Scenario: **Let’s say user A logs into your site at a shared computer and forgets to log out, then user B hops on the same computer. If user B is malicious, they could take actions in user A’s account with the existing session. However, if certain sensitive actions call Hosted Login with prompt=login, user B will be unable to continue those actions without proving ownership of the account.
  - create: The user will be prompted to create an account, rather than shown the sign-in screen.This option is better suited where you have a call-to-action specifically for creating an account, and do not want to provide the option to sign in.
    - **Scenario: **You have a promotion that only applies to new customers. You provide a “Sign up to get 20% off my first purchase” button. Clicking the button calls Hosted Login with prompt=create to present the registration screen to the user, and does not give the option for an existing user to sign in.
- **show_reset_password_screen**=true/false
  - true: Redirect the user to the Password Reset screen.
  - false: Do not redirect user the Passport Reset screen.
- **show_social_signin**=on/off
  - on: Displays the social login options.
  - off: No not display the social login options.