Access and authentication

On the SNAP underlay (see Transport underlays), your app sends its traffic through a SNAP. The SNAP forwards the traffic only if your app shows a valid SNAP token. To get a SNAP token, your app must authenticate with the Anapaya Authentication and Authorization service (Anapaya AA). The Anapaya AA returns SNAP tokens for your subscription. This page explains these terms, and it shows how the SDK gets and renews the SNAP token.

Subscriptions

A SCION subscription gives access to the SCION network through SNAPs. Each subscription has an SSID (SCION subscription ID). The traffic that your app sends through a SNAP is accounted under your subscription.

Resellers and AAs

A reseller sells SCION subscriptions to customers. For each subscription, the reseller selects the AAs that can request SNAP tokens for that subscription.

An AA (Authentication and Authorization service) is the service that your app sends its API key to. The AA authenticates your app with the API key and returns a SNAP token for the corresponding subscription.

Anapaya is a SCION subscriptions reseller and operates the Anapaya AA at https://auth.scion.anapaya.net.

SNAP tokens

A SNAP token is a short-lived bearer credential: a signed JSON Web Token (JWT) with an expiry time. The SNAP verifies the token before it forwards your traffic. Your app does not have to read the token. It gives the token to the SDK.

Token sources

The SDK gets the SNAP token from a token source (TokenSource). You give the token source to the stack with with_auth_token_source when you build it.

Local development

PocketSCION accepts a fixed development token (pocketscion::util::dev_auth_token). The SDK examples give it to the stack as a static token:

examples/common/mod.rs

pub async fn build_stack(ps: &PsSetup, isd_as: IsdAsn) -> anyhow::Result<ScionStack> {
    let endhost_api = ps
        .endhost_api(isd_as)
        .with_context(|| format!("PocketSCION has no endhost API for {isd_as}"))?;

    ScionStackBuilder::new()
        .with_endhost_api(endhost_api)
        .with_auth_token(dev_auth_token())
        .build()
        .await
        .with_context(|| format!("building SCION stack for {isd_as}"))
}

The Anapaya AA token source

The anapaya-aa-client crate supplies AnapayaAaTokenSource. This token source exchanges your API key for a SNAP token at the Anapaya AA. It also renews the SNAP token periodically: before the current token expires, it sends the API key to the Anapaya AA again and gets a new token. Your app does not have to do anything for the renewal.

The HTTP/3 client takes the token source through Config::with_auth_token_source:

examples/http3_get_post.rs

// The client discovers SCION connectivity through the endhost API.
let config = Config::new(endhost_api)
    .with_auth_token_source(AnapayaAaTokenSource::new(API_KEY, &aa_url, DEVICE_ID)?);

Get an API key

To try the SDK on the SCION network, request an Anapaya API key by filling out this form.

Do not put the API key in a public location, for example a public repository. Anyone with the key can get SNAP tokens for your subscription.

Where to go next

• Transport underlays: the SNAP underlay that uses the SNAP token.
• The ScionStack model: the stack that you give the token source to.
• The endhost API: how the stack finds the endhost API, also through the Anapaya AA.