Authentication

This section explains how to authenticate your application with the MapsIndoors API to use the @mapsindoors/built-in-map-edits package. MapsIndoors uses the OAuth 2.0 authorization framework and OpenID Connect (OIDC) for authentication.

---

✅ Getting Ready to Connect

To enable your application to connect to MapsIndoors, you need a client_id. This identifier is used to register your application with the MapsIndoors authentication service. To obtain your client_id, please reach out to MapsPeople support and provide the following details:

• Application Name & Type

• Redirect URIs (must be registered with MapsPeople)

• IdP Configuration (if applicable):

  • Metadata URL (preferred)

  • OR: Issuer, Authorization, Token, and JWKS URLs

• Contact Info

This information allows MapsPeople to configure the authentication service to work with your application, so that your application can securely access the MapsIndoors Platform.

The Authentication Process

Authentication Flow:

1. User Access: A user attempts to use a feature that requires MapsIndoors data.

2. Login Redirect: Your application redirects the user to the MapsIndoors login (or your organization's IdP).

3. User Authorization: The user logs in and authorizes your application.

4. Authorization Code: MapsIndoors (or IdP) redirects back to your application with an authorization code.

5. Token Exchange: Your application exchanges the code for an access token.

6. API Access: Your application uses the access token to make MapsIndoors API requests.

Users must authenticate with MapsIndoors, even if they are already logged in to your application. If your organization uses an external Identity Provider (IdP) and the user is already logged in there, this step may happen automatically (single sign-on). The exact user experience during this authentication step depends on your implementation. For the best user experience, we recommend handling the process in a secondary window to avoid redirecting the user away from your application.

We recommend using oidc-client-ts to manage this process, as it simplifies authentication and token exchange. For practical implementation guidance, explore the oidc-client-ts sample projects on GitHub. These samples demonstrate various authentication flows and configurations, providing valuable insights and learning opportunities.

Sample oidc-client-ts Configuration

Here's a sample configuration for oidc-client-ts:

const settings = {
    authority: 'https://auth.mapsindoors.com/',
    client_id: '{YOUR_CLIENT_ID}', // Replace with your actual client ID provided by MapsPeople.
    redirect_uri: '{YOUR_REDIRECT_URI}', // Replace with your configured redirect URI provided to MapsPeople.
    response_type: 'code', // Use the authorization code flow.
    scope: 'openid profile manager', // Specify the requested permissions.
};

Important Notes about the Configuration:

• Replace {YOUR_CLIENT_ID} with the actual client_id provided by MapsPeople. This is the unique identifier for your application.

• Replace {YOUR_REDIRECT_URI} with the redirect URI you configured with MapsPeople. This URL must match the one provided during the client_id registration process.

• The response_type is set to code, indicating that the authorization code flow is being used.

• The scope parameter specifies the permissions your application is requesting. openid is required for OpenID Connect, profile provides access to user profile information, and manager provides access to the MapsIndoors management API.

---

🚀 Using the Access Token

Once the login sequence is successful, you will receive a MapsIndoors access token. This token is used to authenticate your requests to the MapsIndoors API. To use the access token with the @mapsindoors/built-in-map-edits package, set the accessToken property:

MapsIndoorsEditor.accessToken = accessToken;

---

💡 Additional Resources

For more information on OAuth 2.0 and OpenID Connect, please refer to the following resources:

• OAuth 2.0: oauth.net/2/
• OpenID Connect: openid.net/
• Recommended JavaScript authentication libraries: oauth.net/code/javascript/