13 Secrets Automation

As described in other sections (in particular “A modern approach to authentication” and “Transport security”), all authenticated interactions with 1Password require that the client prove knowledge of the session key without revealing any secrets. That session key in turn can only be established through proof of knowledge or access to the account passwordSomething you must remember and type when unlocking 1Password. It’s never transmitted from your devices. Previously known as Master Password. and Secret KeyA randomly generated user secret key that is created upon first signup. It’s created and stored locally. Along with the user’s account password, it’s required both for decrypting data and for authenticating to the server. The Secret Key prevents an attacker who has acquired remotely stored data from attempting to guess a user’s account password. Previously known as the Account Key..

This aspect of our security design makes it much harder for someone to work their way around 1Password’s authenticationThe process of one entity proving its identity to another. Typically the authenticating party does this by proving to the verifier that it knows a particular secret that only the authenticator should know., as every request to the service is cryptographically bound to the authentication process itself. It also limits the number of authentication attempts a client can perform in a particular time period.

This security design introduces a challenge when automated processes need to retrieve, modify, or create secrets in 1Password. Such apps and processes are not designed to sign in to 1Password directly; typically those processes are designed to authenticateThe process of one entity proving its identity to another. Typically the authenticating party does this by proving to the verifier that it knows a particular secret that only the authenticator should know. through more traditional means. Reauthenticating for each request would be cumbersome at best.

Figure 13.1: The 1Password Connect server lives in your environment and acts as a RESTful connection between your apps and the 1Password service.

The overall solution we provide as part of Secrets Automation is a Connect Server. It’s capable of signing in to 1Password directly, and apps and automated processes can interact with it through a RESTfulThe adjectival form of representational state transfer (REST). See REST interface. The API for the Connect Server can be called by customer-created clients or built with plug-ins we offer.

Any automated process given power over an organization’s resources, particularly the kinds of resources managed within 1Password, creates an area of attack.²³ Therefore, it’s necessary to design them with security in mind. In general, there are two principles to adhere to when deploying automations like these.

• The power allotted to any given automation should be closely tied and limited to what it’s expected to do.
• The credentials required by the automation to perform its duties must be securely managed.

1Password Secrets Automation is designed according to these principles — it’s also design to help customers follow the same principles.

You may want to read through what follows multiple times,²⁴ because many of the interacting parts are mentioned before they’re fully defined. In particular, the descriptions of the credentials JSON and bearer token each depend on each other.

13.1 The Connect server

The Connect server is deployed in your environment and serves as a bridge between the client processes and the 1Password service. Although simple in principle, there are a number of interacting parts, so it’s useful to start with an overview and quick facts about it that will be elaborated on later in this chapter.

• The 1Password Connect server has encrypted credentials necessary to sign in to 1Password under a specific service account.
• The service accounts used by Connect servers are not given any ability to manage users or vaults.
• The Connect server is deployed by the user in the user’s environment. AgileBits has no means of accessing it.
• AuthenticationThe process of one entity proving its identity to another. Typically the authenticating party does this by proving to the verifier that it knows a particular secret that only the authenticator should know. to the Connect server is through use of an HTTP Authorization header bearer token.
• The credentials necessary to sign in as the service account are split between what’s stored with the Connect server and bearer token.

13.1.1 Service account

1Password service accounts aren’t highly visible to users, but it’s important to mention them to better describe how Secrets Automation works in practice.

Generally speaking, a service account is a special user within a 1Password account, but the user isn’t associated with a person or group of people. They help an organization manage the secrets used by entities with very specific roles and functions.

If Patty, a member of a 1Password account, is responsible for ensuring backups can be restored, they may need access to the credentials for the backups system. But the automated processes that perform backups and restorations shouldn’t have all of Patty’s 1Password privileges. They should only have the privileges required to perform their duties.

The appropriate service accounts are set up in 1Password when setting up Secrets Automation. During creation of a service account, the administrator will select which vaults the service account will have access to and share those vaults with the service account. In this respect, the service account is like an ordinary user. Unlike an ordinary user, the service account has no management privileges and will be prevented from further sharing the vaults to which it has been given the keys by the 1Password backend system.

The account passwordSomething you must remember and type when unlocking 1Password. It’s never transmitted from your devices. Previously known as Master Password. for the service account is randomly generated and discarded after deriving the Account Unlock Key (AUK)Key used to decrypt a user’s personal key set. It’s derived from the user’s account password and Secret Key. Previously known as the Master Unlock Key. and SRP-\(x\)The client secret, 𝑥, used by the Secure Remote Password (SRP) protocol. Derived from the user’s account password and Secret Key.. Key generation is performed client side, either in the web client or the command-line interface (CLI).

Dangerous bend

The service accounts created for Secrets Automation complement the ones created for use by the SCIM bridge, and used for automated management of 1Password users. They have the ability to create and delete users, and add users to groups, but no ability to retrieve data from vaults.

13.1.2 Local deployment

The Connect server, with the encrypted 1Password credentials, is deployed on your system. At initial release, April 2021, we provided setups for deploying it within a Docker container or via Kubernetes. At no time does AgileBits have access to the Connect server or data it stores.

13.1.3 Credential store

The Connect server locally stores encrypted credentials, containing the AUKKey used to decrypt a user’s personal key set. It’s derived from the user’s account password and Secret Key. Previously known as the Master Unlock Key. and SRP-\(x\)The client secret, 𝑥, used by the Secure Remote Password (SRP) protocol. Derived from the user’s account password and Secret Key. for the associated service account. This saves it from having to go through the entire key derivation process each time it needs to start a 1Password session.

Figure 13.2: An overview of the credentials file, with three major components and some header information.

13.1.4 The credentials file

When setting up a Connect server initially, the user’s 1Password client constructs a 1password-credentials.json file along with a bearer token. The credentials file has three substantive components: The verifier is used as part of an additional authentication of the bearer token; encCredentials contain the encrypted credentials necessary for the associated service account to sign in to 1Password; and uniqueKey is key shared between the client-facing Connect server and the Connect server syncher.

13.1.5 Encrypted credentials

The encrypted credentials, illustrated in Figure 13.3 contain, unsurprisingly, the encrypted 1Password credentials required to unlock 1Password as the associated service account.

Figure 13.3: The encCredentials object is a JSON web key (JWK) used to encrypted 1Password unlocking credentials. It’s encrypted with a key derived from the bearer token.

Encryption, as with all our symmetric encryption, is with Advanced Encryption Standard (AES)Probably the best studied and most widely used symmetric block cipher. using Galois Counter Mode (GCM)An authenticated encryption mode for use with block ciphers. for authenticated encryption. The nonceA non-secret value used in conjunction with an encryption key to ensure relationships between multiple plaintexts are not preserved in the encrypted data. Never encrypt different data with the same combination of key and nonce. Ideally, most software developers using encryption – as they should – would never have to interact with or much less understand the difference between them. We do not live in such a world. is given in the \(iv\).

When decrypted, the object is structured as in the Golang structure in Figure 13.4. The URL will typically be something like example.1password.com; the email addresses created for service accounts are never expected to be used for email, and only serve as a username. The user Universally Unique Identifier (UUID)A large arbitrary identifier for an entity. No two entities in the universe should have the same UUID. uniquely identifies the service account Secret KeyA randomly generated user secret key that is created upon first signup. It’s created and stored locally. Along with the user’s account password, it’s required both for decrypting data and for authenticating to the server. The Secret Key prevents an attacker who has acquired remotely stored data from attempting to guess a user’s account password. Previously known as the Account Key.²⁵, SRP-\(x\)The client secret, 𝑥, used by the Secure Remote Password (SRP) protocol. Derived from the user’s account password and Secret Key., and AUKKey used to decrypt a user’s personal key set. It’s derived from the user’s account password and Secret Key. Previously known as the Master Unlock Key. are as described in “A deeper look at keys.”

Figure 13.4: Decrypted credential structure. The URL, Email, UserUUID, and SecretKey are used to identify the user, account, and service. The SRP-\(x\) and AUK are the secrets required to authenticate with 1Password and decrypt (the keys needed to decrypt the keys which encrypt) the vault data.

Figure 13.5: Connect server verifier

13.1.6 Verifier

The token within the bearer token is run through a key derivation function, which must match the verifier stored by the Connect server.

This verification is redundant, as the signature verification of the entire bearer token provides all the authenticationThe process of one entity proving its identity to another. Typically the authenticating party does this by proving to the verifier that it knows a particular secret that only the authenticator should know. necessary and guarantees the integrity of the request.

13.1.7 Interprocess key

The 1Password Connect server has two running processes. One provides the user-facing service while the other synchronizes data with 1Password itself. Among other things, this allows the Connect server to operate even when a direct connection to 1Password is unavailable.²⁶ This also allows for much faster responses from the Connect server. The data stored by the sync server is encrypted as with any 1Password client.

Figure 13.6: Connect server IPC key. The Connect server interprocess key is used to secure communication between the sync server and the client facing Connect service.

The interprocess key, here called uniqueKey²⁷ is used as a shared secret between the client-facing Connect server and synchronization server in order to encrypt the bearer token between them.

13.2 Bearer token

The bearer token is a JSON web token (JWT)A means of representing claims to be transferred between two parties and defined in RFC 7517. These are typically signed cryptographically. that’s transmitted from the user’s client process to the Connect server using the HTTP Authorization header. It contains a key that’s used, indirectly, to decrypt the 1Password credentials stored by the Connect server. It also contains claims, in the JWT sense, listing what 1Password vaults it has access to. As a signed JWT, it’s also used directly for authenticationThe process of one entity proving its identity to another. Typically the authenticating party does this by proving to the verifier that it knows a particular secret that only the authenticator should know. to the Connect server. Serialized JWTs are composed of three base64-encoded parts: header, payload, and signature. These parts are separated by the “.” character.

Figure 13.7: Sample JWT header for bearer tokens

13.3 Header

An example header portion is shown in Figure 13.7. The kid identifies the signing key of the corresponding service account key setHow collections of keys and their metadata are organized within 1Password., which is used to sign the bearer token. It must be a key belonging to the subject field in the payload.

Dangerous bend

Although Elliptic Curve Digital Signature Algorithm (ECDSA) isn’t the most robust of digital signature algorithms, it’s the one we settled on for the timebeing, as it’s widely available in well-vetted cryptographic libraries. We find it particularly important to whitelist the algorithms that we accept in a JWT, because it helps avoid a number of security concerns²⁸ surrounding JSON Object Signing and Encryption (JOSE) and JWT.

In particular, the flexibility of signature and encryption algorithms can lead to downgrade attacks. In addition to whitelisting signature algorithms (currently ECDSA using P-256 and SHA-256 (ES256) is the only one the Connect server will accept) our verification process is very aggressive in rejecting inconsistent or malformed tokens.

13.3.1 Payload

A sample payload, or claims, portion of the bearer token can be seen in Figure 13.8.

Figure 13.8: Sample JWT payload for bearer tokens. AUUID is the account UUID, and the subject sub is the user UUID for the service account user. The features, fts, will always be vaultaccess for Secrets Automation. The token is both an authentication secret to the Connect server and key used to derive the key to decrypt the 1Password credentials stored on the Connect server.

Most of what appears in the figure can be understood from the JWTA means of representing claims to be transferred between two parties and defined in RFC 7517. These are typically signed cryptographically. standards, which you may peruse at your leisure. What requires explanation follows.

• sub The subject of the bearer token is the UUID of the service account that signs into 1Password.
• auuid The account UUID.
• fts Features will always be “vaultaccess" for Secrets Automation.
• vts The vaults the client is claiming access to, along with its read and write claims.
• token The token which, among other things, is used to decrypt credentials stored by the Connect server.

It’s worth noting that a particular service account may have more access to more vaults than claimed in the bearer token payload. The Connect server won’t honor client requests that go beyond the validated claims.

For example, if the associated service account has the ability to read and write to vaults \(V_1\) and \(V_2\), while the signed claim is only for reading \(V_1\), the Connect server will only honor read requests for \(V_1\). Naturally, if the service account associated with one of these tokens doesn’t have any access to \(V_3\) but somehow shows up with a valid claim to it, the Connect server will reject the claim.

Even if the Connect server were somehow tricked into honoring such a claim, the 1Password service wouldn’t return the data, and the Connect server wouldn’t be able to decrypt the data even if it were returned.

13.3.2 Signature

The third part of the bearer token is the JWTA means of representing claims to be transferred between two parties and defined in RFC 7517. These are typically signed cryptographically. signature. The signature is created by the associated service account using that account’s signing key. This signature covers the payload of the bearer token, preventing tampering or forgery.

---

23. This is true whether or not those processes are systematically managed within an organization or are left untracked. It is not difficult to guess which might introduce more risk.↩︎

24. Or, perhaps, zero times.↩︎

25. It’s only the non-secret part of the Secret Key used in the process. All service account identifying information must be consistent for successful authentication.↩︎

26. This might be particularly handy if you are managing your network equipment with Secrets Automation.↩︎

27. All keys are unique, but are some keys more unique than others? They’re all unique, but coming up with names for yet another key when developing something is difficult, and the temporary placeholder name may stick around longer than anyone might expect.↩︎

28. Arciszewski (2017)↩︎