OAuth 2.0 Integration Overview

This is a user guide for integrating Jiomeet OAuth 2.0 apps within your application.

Introduction

JioMeet Server uses OAuth 2.0 industry-standard protocol for authorization.

OAuth 2.0, short for "Open Authorization," is a widely adopted standard designed to enable websites or applications to obtain access to resources hosted by other web applications on behalf of a user. It ensures authorized access with the user's consent while imposing limitations on the actions that the client application can take concerning user resources, all without the need to divulge the user's credentials.

To make API requests on behalf of a user, you will need to receive and securely store an access token provided by Jiomeet's OAuth authorization flow. Use this access token as a Bearer token passed within the Authorization header in the Jiomeet API requests.

Request OAuth feature

Currently, OAuth is available in Beta and is provided to accounts upon request. To enable OAuth for your account, kindly contact us at jiomeet.support@jio.com.

Creating an OAuth App on JioMeet

Once you have a user account with JioMeet Server, and OAuth enabled for your account, you can create an Oauth app on the Jiomeet platform.

1. Accessing the OAuth Section

• Click on "Oauth" on left side bar.
• Click on "Create new Oauth app".

2. Filling Out App Information

• App Info: Basic details about your app

  • App Name: Give your app a unique and meaningful name.
  • Homepage URL: The full url to your application homepage.
  • Policy URL: Enter your application policy url.
  • Logo URL: Enter your application logo url.
  • Use case: Select a use case, from the drop down menu.
  • Description: Provide a short description about your app (optional).

• Authorization callback URLs: One or more URLs that a user will be redirected upon completing an OAuth authorization flow.

  • Auth callback URL(1-10): Valid redirect URL.

• Scopes: Scopes provide a way to limit the amount of access which granted would be granted to user access token

  • Define the access level for user tokens. For an in-depth understanding, refer to the Scopes section
    • user:read
    • meeting:create
    • meeting:delete
    • meeting:read
    • meeting:update
    • meeting:join

• Once all fields are populated, click "Create OAuth app".

3. Post-Submission

• After submission, your OAuth app will be reviewed.
• The typical review duration is 24-48 hours.
• Monitor the status of your OAuth app in the "OAuth" section.
• If your app is rejected or put on hold, refer to your OAuth app page to understand the reason.

URL best practices

• It is a good practice that Redirect URLs uses the HTTPS scheme, not plain HTTP
• Hosts cannot be raw IP addresses
• The URLs should not contain the following query parameters: "sessionId", "token", "success", "redirect_uri", "clientId"
• The URLs cannot contain certain characters including:
  • Wildcard characters ('*')
  • Fragment component(‘#’)

OAuth App Rejection Reasons:

If your OAuth app is not approved, it could be due to the following reasons:

• Invalid URLs:

  • These are URLs that do not adhere to the standard URL format or contain prohibited characters. They might be broken or lead to non-existent pages. Ensure that all URLs provided are accessible and correctly formatted.

• Malicious URLs:

  • URLs that lead to sites containing malware, phishing schemes, or any other harmful content. JioMeet aims to protect its users, and any URL suspected of malicious intent will result in rejection. Always ensure your URLs are safe and free from harmful content.

• Suspicious URLs:

  • These are URLs that might not necessarily be malicious but raise concerns due to their content, domain history, or other associated factors. It could be a newly registered domain, a domain with a history of changing ownership frequently, or a site with hidden content. Ensure your URLs are from reputable sources and have a clear, user-friendly content.

Always double-check your application details before submission and ensure that all URLs provided adhere to best practices and are free from any harmful or suspicious content.

OAuth App Credentials

Once your OAuth app has passed the review process

• Check your OAuth app Client ID and Client Secret

  • Click on your app
  • Scroll to security section
    • Client Id: OAuth app Client ID.
    • Client Secret: OAuth app client secret.(You can regenerate this)

OAuth Scopes:

OAuth scopes define the specific actions a client application is allowed to perform on behalf of the user. By specifying scopes in the authorization request, the client indicates which permissions it needs. The user then grants or denies these permissions during the authorization process.

Here are the currently available scopes for the JioMeet platform:

User Scopes:

• user:read:
  • Description: Allows the client application to read the user's profile information.

Meeting Scopes:

• meeting:create:

  • Description: Grants the client application permission to create new meetings on behalf of the user.

• meeting:delete:

  • Description: Allows the client application to delete existing meetings that were created by the user.

• meeting:read:

  • Description: Grants the client application read access to the user's meetings, including details and participants.

• meeting:update:

  • Description: Allows the client application to update the details of meetings created by the user.

• meeting:join:

  • Description: Allows the client application to pass access token to Jiomeet Web SDK to join the meetings of jiomeet.

For detailed API specifications, please refer to the Jiomeet OAuth API's documentation.

OAuth Authorization Flow

Jiomeet utilizes the OAuth Authorization Code Grant Type, a server-side flow where the client (typically a web application) redirects the user to Jiomeet's authorization page for authentication. Once authenticated, the user is redirected back to the client with an authorization code. This code is then exchanged for an access token, which can be used to access Jiomeet's protected resources.

1. Login/Authorization Page:

• The user initiates the process by trying to access a Jiomeet resource that requires authentication at client app.
• The client redirects the user to Jiomeet's login or authorization page.

2. Authorization Request:

• The client app makes an authorization request to Jiomeet's authorization server using the Jiomeet OAuth Authorization URL

https://jiomeetpro.jio.com/oauth2/authorize?clientId=<CLIENT_ID>&redirect_uri=<REDIRECT_URL>&response_type=code&state=<BASE_64_STRING>

• clientId:

  • A unique identifier provided by Jiomeet upon OAuth application registration.
  • Recognizes the client and ensures users grant permissions to the correct application.
  • Access this from the OAuth page security section.

• redirect_uri:

  • The designated URL where Jiomeet redirects users after they decide to grant or deny permissions.
  • Must match the URL specified during OAuth application registration to prevent redirection attacks.

• state:
  • An optional but highly recommended parameter acting as a CSRF token.
  • A base64 encoded JSON string generated and sent by the client application.
  • Jiomeet's authorization server will return this value when redirecting the user back to the client.
  • The client must decode the base64 string, parse the JSON, and confirm that the returned state matches the original request's state to validate the response's integrity.

3. Jiomeet Login/Authorization page:

• The user is redirected to a secure Jiomeet Login page to input their account credentials and verify their identity.

4. Authenticate & Scope Consent

• Jiomeet's authorization server authenticates the user's credentials.
• The user is presented with a consent screen where they grant the requested permissions (scopes) to the client.

5. Issue Authorization Code:

• Upon successful authentication and consent, Jiomeet's authorization server issues an authorization code to the client.
  • Authorization Code: The Authorization Code has a validity period of 5 minutes.

6. Request for Access Token:

• The client sends the authorization code back to Jiomeet's authorization server to exchange it for an access token and refresh token.

• Generating Authorization Header:

  // Replace with your actual JioMeet OAuth client ID and secret key.
  const clientId = "your-client-id";
  const clientSecret = "your-secret-key";
  
  // Concatenate the client ID and secret with a colon separator.
  const keys = clientId + ":" + clientSecret;
  
  // Encode the concatenated values into a base64 string.
  // This encoded string will be used for the Authorization header in the token request.
  const authEncodedKeys = Buffer.from(keys).toString('base64');

  Sample curl:

  curl -X POST https://jiomeetpro.jio.com/api/oauth2/v2/token \
  -H "Authorization: Basic {authEncodedKeys}" \
  -d "grant_type=authorization_code&code={YOUR_AUTHORIZATION_CODE}"
  

  For detailed specifications on the access token request, please refer to the Jiomeet Access Token Endpoint documentation.

7. Receiving Tokens and Scope:

• Token Validation and Issuance:

  • Upon receiving the authorization code, Jiomeet's authorization server verifies its validity. If the code is valid, the server issues both an access token and a refresh token (if applicable) to the client, along with the granted scopes.

• Token Details:

  • Access Token:
    • Validity: 1 day.
    • Usage: This token grants the client application the ability to access specific user resources as defined by the granted scopes.
  • Refresh Token:
    • Validity: 60 days.
    • Usage: This token allows the client application to obtain a new access token once the initial access token expires, without requiring the user to re-authenticate.

• Scope:

  • Definition: Scopes define the specific actions or resources the client application is allowed to access on behalf of the user.
  • Example Response:

    {
      "scope": "meeting:create meeting:delete meeting:update meeting:read user:read"
    }
  • Granted Scopes Interpretation: In the example response, the user has granted the client application permissions to create, delete, update, and read meetings, as well as read the user's profile. The client application can perform actions based on these scopes but cannot perform actions outside of these granted permissions.

8. Request User Data with Access Token:

• The client uses the access token to request user data or other protected resources from Jiomeet's user API. @TODO Add user profile request and refrence to User OAuth API's

    GET /api/user/profile
    Authorization: Bearer YOUR_ACCESS_TOKEN
  For more details on the available endpoints and their specifications, please refer to the Jiomeet OAuth API's documentation.

9. Return Response:

• Jiomeet's user API validates the access token and, if valid, returns the requested data to the client.

Key Considerations for Jiomeet Integration:

• Jiomeet adopts the Authorization Code Grant Type, optimized for web servers that can maintain the confidentiality of the client secret.
• The refresh token allows the client to obtain a new Jiomeet access token without requiring the user to re-authenticate.
• The access token is short-lived, while the refresh token usually has a longer lifespan.
• Prioritize security by ensuring all interactions with Jiomeet's Authorization server (especially Access/Refresh Token requests) and Jiomeet User APIs are routed through your web application's backend server, mitigating CORS issues.
• Ensure that the redirect URI used in the flow is registered with Jiomeet and cannot be manipulated.
• Always use HTTPS to ensure data confidentiality and integrity when interacting with Jiomeet.
• Store the client secret securely and never expose it.
• Implement proper error handling to manage any errors that may arise during the Jiomeet OAuth flow.

By following this grant type, applications can securely obtain user consent and access Jiomeet's protected resources without exposing user credentials.