Identities & Authentication
Identities
Decentralized Identifiers (DIDs)
Identities in Habitat are based on DIDs. Both organizations and members of an organization have a unique identity, defined by a DID document. The did:web: DID method is used for all identities in Habitat. Application developers should reference both organizations and users by DID. Currently, the DID docs for both organizations and users only have a single service in the services field, a #habitat service which points to the ODS (Organizational Data Server) on which the identity lives. Because Habitat is starting with the permissioned data usecase, the #atproto_PDS service would be an inaccurate service to include, though eventually we will reach parity with that and switch over.
Organization identities
Every organization in Habitat has its own identity. This is a did:web: that directly references the Habitat domain the organization is hosted on. For organizations that use the managed hosting provided by Habitat's main instance, this looks like <org-name>.id.habitat.network. For self-hosted instances, this is <org-name>.<domain where habitat is running>.
User identities
Habitat uses DIDs (Decentralized Identifiers) as the foundation of user identity. Every user is identified by their DID, and has a handle that is tied to the organization. The username that is in this handle is chosen by the user when they are added as a member of the organization. So, for example, alice.acmecorp.id.habitat.network is the AT Protocol handle for a user Alice who is a part of the Acmecorp organization hosted by Habitat. (These handles will be tied to organization-given domains and shortened in the future).
Authentication
Login methods
When creating a Habitat organization, admins will be prompted about which login method to set for the entire organization. The options offered today are sign-in with password, sign-in with AT Protocol, and sign-in with Google. Choosing a login method is a final operation and cannot be changed in the future. We currently do not support multiple login methods for an organization, though we may in the future. Every login method creates a DID for the user within Habitat's Organizational Data Server, but the AT Protocol and Google login methods defer to those services for authentication.
OAuth
Habitat's Organizational Data Server runs its own OAuth 2.0 server, which is what your app authenticates with on behalf of both users and on behalf of the application itself. You can use a standard OAuth client that supports PKCE to authenticate with Habitat's OAuth server. The OAuth flow will redirect the user to a Habitat consent screen before navigating back to your page once the auth flow has completed. See an example of how we do it here.
Admin-approved applications
Applications that are built on Habitat must get organization approval in order to receive an OAuth credential for the org's identity, which allows the app to read and write to the Habitat Data Server. Applications must implement a flow that redirects to Habitat to request relevant permissions, and from which authenticated admins can either approve or deny the request. This flow is currently a work-in-progress and updated documentation is coming soon.
Service Auth
The Habitat Data Server also supports service proxying for authenticated inter-service requests.