Configuring your scope

Introduction

Scopes within the Passport Protocol act as programmable key management namespaces / configurations. By creating a scope you can:

  • Organise: Keep your authentication methods and settings arranged in a clear way.

  • Control: Set specific permissions and policies for each scope.

  • Customise: Pick from authentication methods like OAuth, 2FA or more, that suit your needs.

Setup

Install passport-scope-cli

npm install -g passport-scope-cli

After installation, try passport-scope in your terminal to see if it is installed:

% passport-scope
Usage: passport-scope [options] [command]

Available Commands

  • -V, --version: output the version number

  • -h, --help: display help for command

  • create [options]: Create a new scope based on the provided configuration.

Commands

Generate Keys

  • Create a new keys for your scope if you haven't created one already.

  • This should create two files

    • <KEY_NAME>_pub.der

    • <KEY_NAME>_priv.der

passport-scope generate-keys --name <KEY_NAME>

Create Scope:

  • This method creates a new scope based on the provided configuration file.

  • Upon execution, you should receive a scope_id as output.

  • The system generates a temporary random wallet for every scope.

passport-scope create --config-path ./<YOUR_CONFIG_FILE>.json --private-key ./<KEY_NAME>_priv.der --network testnet --verbose

Note: Always exercise caution with private keys. While the key isn't stored or used for any purpose other than signing, it's crucial to avoid using a private key that is already exposed with other services. Always opt for a freshly key pair dedicated solely to managing scopes.

Detailed configuration structures are as follows:

Option
Description

--config-path

Path of the scope configuration content

--network

The network you'd like to use can be testnet / mainnet / localhost

--private-key

Path of the private key that is going to be the owner of the scope. If not provided, a new key pair is

Scope Configuration

Define the authentication rules for the scopes you own in JSON format.

Passkeys

Here's a simple structure for a scope supporting Passkeys:

{
  "rp": {
    "id": "demo.0xpass.io",
    "origin": "https://demo.0xpass.io/",
    "name": "Text Relying Party"
  },
  "policies":[]
}

Here are the components of the scope config

  • rp: configurations for webauthn relaying party.

    • id: the domain of where the passkey is generated

    • origin: full url of the domain

    • name: human readable name for the domain

Keep track of your Scope ID

Upon successful creation of the scopes, take note of the scope_id.

This scope_id is essential for initializing the Passport instance. For a comprehensive integration guide, please consult the Quickstarts and Examples sections.

Updating a Scope

Updating a scope is same as creating a scope, except you specify a scope id.

passport-scope update --scope-id ed5fdb5c-53f3-4a0f-a7af-53b0f09121bb --config-path ./<YOUR_CONFIG_FILE>.json --private-key ./<KEY_NAME>_priv.der --network testnet --verbose

Next Steps

Once you have your scope ID, you can now proceed to the appropriate authentication method sections to continue with your integration.

PreviousOverviewNextPasskeys

Last updated