Skip to main content

Adding OpenID Connect to Your App

This guide will walk you through how to quickly add Basic authentication to your application without code changes by using ngrok tunnels.

ngrok provides a variety of authentication options such as Basic Authentication, OpenID Connect, and SAML.

OpenID Connect (OIDC)​

OpenID Connect (OIDC) is an open identity layer protocol built on top of the OAuth 2.0 framework. It provides a secure and scalable identity layer for authentication and authorization. It leverages industry-standard encryption algorithms and token-based authentication, enhancing the overall security of the application.

OIDC brings to the table the concept of an Identity Provider, i.e. an external application that provides authentication services to relying applications. Applications can then benefit from identity provider's features such as social login, multi-factor authentication, and other security-enchanced measures, to expand their options for user authentication.

ngrok integrates with a variety of them. For example, Auth0, Curity, Facebook, FusionAuth, Google, JumpCloud, LinkedIn, MiniOrange, Okta, Wallix Trustelem, and others. See ngrok partners.

By adding OIDC to your application you also enable the application to participate in the Single Sign-On (SSO) provided by the identity provider: users authenticate once and access multiple applications seamlessly.

The OIDC widespread adoption and active developer community ensure continued support, updates, and security improvements, providing a standardized, secure, and flexible solution for protecting your application.

Command line configuration​

Use the --oidc, --oidc-client-id, and --oidc-client-secret flags with your ngrok agent to enable an identity provider for your application with no code changes.

For example, if you want to enable OIDC with Google run the following command:

ngrok http --oidc=https://accounts.google.com --oidc-client-id=GOOGLE_OAUTH2_CLIENT_ID --oidc-client-secret=GOOGLE_OAUTH2_CLIENT_SECRET 3000

Note: The oidc URL is the base URL where the identity provider exposes the well-known configuration endpoint (i.e. https://accounts.google.com/.well-known/openid-configuration).

Note: Replace the GOOGLE_OAUTH2_CLIENT_ID and GOOGLE_OAUTH2_CLIENT_SECRET values with the ones you get from the Google Cloud Credentials page after setting up an OAuth consent screen and creating an OAuth Client ID Credential.

Using Configuration File​

Instead of passing the values as arguments to the ngrok agent, you can set up the Agent Configuration File.

  1. Set up the ngrok authtoken and run the following command to create and edit a configuration file:

    ngrok authtoken NGROK_AUTHTOKEN
    ngrok config edit

  2. Add a tunnel definition at the end of the configuration file as follows:

    tunnels:
      mytunnel: 
        proto: http
        addr: 3000
        oidc:
            issuer_url: https://accounts.google.com
            client_id: GOOGLE_OAUTH2_CLIENT_ID
            client_secret: GOOGLE_OAUTH2_CLIENT_SECRET
            scopes: []

    Note: In this example, we used Google as the identity provider. Follow the documentation of your preferred OIDC identity provider to collect the valid values for issuer_url, client_id, client_secret, and scopes.

  3. Run the ngrok agent using the following command:

    ngrok start mytunnel

    The ngrok agent provides a Forwarding URL to expose your application to the internet (i.e. https://1a2b-3c4d-5e6f-7g8h-9i0j.sa.ngrok.io).

Test the Authentication​

Test the integration.

Test the application access in a browser:​

  1. Open the Forwarding URL provided by the ngrok agent in a web browser and the Sign in with Google page appears.

  2. Provide your Google credentials and after successfully logging into Google the browser will be redirected to your application.

    Note: Make sure you have a localhost application running on port 3000. Use the sample NodeJS app available on GitHub.

Programmatically access the application.​

  1. Execute the following command line to access the application:

    curl --location 'NGROK_AGENT_FORWARDING_URL' --header 'Authorization: Bearer TOKEN'

    Note: Replace the TOKEN value with a valid access token from Google.

    Verify that the application responds correctly.

After Authentication​

After the credentials are validated by the ngrok tunnel, the agent forwards to the application some headers containing information about the logged-in user. Therefore the application can use the information inside these headers (this may require some application code changes).

"ngrok-auth-user-email": "myuser@gmail.com"
"ngrok-auth-user-id": "1234567890"
"ngrok-auth-user-name": "My User"