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:
User Access: A user attempts to use a feature that requires MapsIndoors data.
Login Redirect: Your application redirects the user to the MapsIndoors login (or your organization's IdP).
User Authorization: The user logs in and authorizes your application.
Authorization Code: MapsIndoors (or IdP) redirects back to your application with an authorization code.
Token Exchange: Your application exchanges the code for an access token.
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
:
Important Notes about the Configuration:
Replace
{YOUR_CLIENT_ID}
with the actualclient_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 theclient_id
registration process.The
response_type
is set tocode
, 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, andmanager
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:
💡 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/
Last updated