Signed Identity

Signed Identity is a more secure way to provide contact identifiers. When the user logs in on your website or mobile app, your backend server will return a signed payload containing the identifiers for this user. This signed payload is called SignedIdentity. Take a look at the following sequence diagram:

Identify Contact with Signed Identity

After the signed identity is retrieved, your web or mobile application can use it to identify the contact as follows:

Android (Kotlin)

// Call backend server for user login
val response = userLogin()

// and get signed identity
val signedIdentity = response.signedIdentity

bird.contact.identify( SignedIdentity(signedIdentity) )

iOS (Swift)

// Coming soon...

Web (Js)

// Coming soon...

Generate Signed Identity

The backend server can generate a signed identity for a user as follows:

• Get the signing key and issuer from the application settings in the Bird dashboard (Developer > Applications > (your application) > Overview tab).

• Sign the user identifiers payload using the signing key.

Here is a sample code to get you started:

Node.js

const crypto = require('crypto');

let issuer = "<your-app-signing-key-issuer>";
let signingKey = "<your-app-signing-key>";

async function onUserLogin() {
    // Authenticate the user in your system
    
    // Make SignedIdentity with a list of identifiers for this user
    let identifiers = [
        {
            key: "emailaddress",
            value: "[e-mail]",
        }
    ]
    let signedIdentity = await makeSignedIdentity(identifiers);

    // Include signedIdentity in the response to the login operation.
}

async function makeSignedIdentity(identifiers) {
    let header = JSON.stringify({
        "alg": "HS256",
        "typ": "JWT",
        "kid": issuer,
    });
    let payload = JSON.stringify({
        identifiers: identifiers
    });
    let headerBase64 = Buffer.from(header).toString('base64url');
    let payloadBase64 = Buffer.from(payload).toString('base64url');
    let signature = crypto.createHmac('sha256', signingKey).update(headerBase64 + "." + payloadBase64).digest('base64url');
    let signedIdentity = headerBase64 + "." + payloadBase64 + "." + signature;
    return signedIdentity;
}

Go

func makeSignedIdentity(identifiers []Identifier) (string, error) {

	issuer := "<your-app-signing-key-issuer>"
	signingKey := "<your-app-signing-key>"

	// Create JWT header
	header := map[string]string{
		"alg": "HS256",
		"typ": "JWT",
		"kid": issuer,
	}

	headerJSON, err := json.Marshal(header)
	if err != nil {
		return "", err
	}
	headerBase64 := base64.RawURLEncoding.EncodeToString(headerJSON)

	// Create JWT payload
	payload := map[string]interface{}{
		"identifiers": identifiers,
	}

	payloadJSON, err := json.Marshal(payload)
	if err != nil {
		return "", err
	}
	payloadBase64 := base64.RawURLEncoding.EncodeToString(payloadJSON)

	// Sign the header and payload
	dataToSign := headerBase64 + "." + payloadBase64
	h := hmac.New(sha256.New, []byte(signingKey))
	h.Write([]byte(dataToSign))
	signature := base64.RawURLEncoding.EncodeToString(h.Sum(nil))

	// Combine all parts into the final JWT
	signedIdentity := fmt.Sprintf("%s.%s.%s", headerBase64, payloadBase64, signature)
	return signedIdentity, nil
}


func loginHandler(w http.ResponseWriter, r *http.Request) {

	// Authenticate the user in your system
	user := Authenticate(r)

	// Make SignedIdentity with a list of identifiers for this user
	identifiers := []Identifier{
		{
			Key:   "emailaddress",
			Value: user.Email,
		},
	}

	signedIdentity, err := makeSignedIdentity(identifiers)
	
	w.Write([]byte(signedIdentity))
}