loginsessionspb

type CreateLoginSessionRequest struct {

	// An OAuth2 client ID that should be known to the login sessions server.
	//
	// The eventual outcome of the login protocol is a set of tokens associated
	// with this OAuth2 client (e.g. the ID token will have this client as
	// `aud` claim).
	//
	// This client ID also identifies the application information that the user
	// will see at the OAuth2 consent screen.
	//
	// Required.
	OauthClientId string `protobuf:"bytes,1,opt,name=oauth_client_id,json=oauthClientId,proto3" json:"oauth_client_id,omitempty"`
	// A list of OAuth2 scopes to get the refresh and access tokens with.
	//
	// The server may deny usage of some sensitive scopes. This set of scopes
	// defined what the user will see at the OAuth2 consent screen.
	//
	// Required.
	OauthScopes []string `protobuf:"bytes,2,rep,name=oauth_scopes,json=oauthScopes,proto3" json:"oauth_scopes,omitempty"`
	// A `code_challenge` parameter for PKCE protocol using S256 method.
	//
	// See https://tools.ietf.org/html/rfc7636. It should be a base64 URL-encoded
	// SHA256 digest of a `code_verifier` random string (that the caller should
	// not disclose anywhere).
	//
	// Required.
	OauthS256CodeChallenge string `` /* 131-byte string literal not displayed */
	// A name of the native program that started the flow.
	//
	// Will be shown on the confirmation web page in the login session UI to
	// provide some best-effort context around what opened the login session.
	// It is **not a security mechanism**, just an FYI for the user.
	//
	// Optional.
	ExecutableName string `protobuf:"bytes,4,opt,name=executable_name,json=executableName,proto3" json:"executable_name,omitempty"`
	// A hostname of the machine that started the flow.
	//
	// Used for the same purpose as `executable_name` to give some context around
	// what opened the login session. It is **not a security mechanism**, just
	// an FYI for the user.
	//
	// Optional.
	ClientHostname string `protobuf:"bytes,5,opt,name=client_hostname,json=clientHostname,proto3" json:"client_hostname,omitempty"`
	// contains filtered or unexported fields
}

type GetLoginSessionRequest struct {

	// ID of the login session to get the state of. Required.
	LoginSessionId string `protobuf:"bytes,1,opt,name=login_session_id,json=loginSessionId,proto3" json:"login_session_id,omitempty"`
	// The password returned by CreateLoginSession. Required.
	LoginSessionPassword []byte `protobuf:"bytes,2,opt,name=login_session_password,json=loginSessionPassword,proto3" json:"login_session_password,omitempty"`
	// contains filtered or unexported fields
}

type LoginSession struct {

	// Globally identifies this session.
	//
	// It is a randomly generated URL-safe string. Knowing it is enough to
	// complete the login session via the web UI. Should be used only by the user
	// that started the login flow.
	//
	// It will also appear as a `nonce` claim in the ID token produced by the
	// protocol.
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// Password is required to call GetLoginSession.
	//
	// It is populated only in the response from CreateLoginSession. It exists
	// to make sure that only whoever created the session can check its status.
	// Must not be shared or stored.
	Password []byte             `protobuf:"bytes,2,opt,name=password,proto3" json:"password,omitempty"`
	State    LoginSession_State `protobuf:"varint,3,opt,name=state,proto3,enum=luci.auth.loginsessions.LoginSession_State" json:"state,omitempty"`
	// When the session was created. Always populated.
	Created *timestamppb.Timestamp `protobuf:"bytes,4,opt,name=created,proto3" json:"created,omitempty"`
	// When the session will expire. Always populated.
	Expiry *timestamppb.Timestamp `protobuf:"bytes,5,opt,name=expiry,proto3" json:"expiry,omitempty"`
	// When the session moved to a final state. Populated for finished sessions.
	Completed *timestamppb.Timestamp `protobuf:"bytes,6,opt,name=completed,proto3" json:"completed,omitempty"`
	// A full URL to a webpage the user should visit to perform the login flow.
	//
	// It encodes `id` inside. Always populated.
	//
	// Knowing it is enough to complete the login session via the web UI. Should
	// be used only by the user that started the login flow.
	LoginFlowUrl string `protobuf:"bytes,7,opt,name=login_flow_url,json=loginFlowUrl,proto3" json:"login_flow_url,omitempty"`
	// How often the caller should poll the session status via GetLoginSession.
	//
	// It is a mechanism to adjust the global poll rate without redeploying
	// new clients.
	//
	// Populated for sessions in PENDING state. The caller is allowed to ignore it
	// if absolutely necessary.
	PollInterval *durationpb.Duration `protobuf:"bytes,8,opt,name=poll_interval,json=pollInterval,proto3" json:"poll_interval,omitempty"`
	// The active confirmation code.
	//
	// The user will be asked to provide this code by the web UI as the final step
	// of the login flow. The code should be shown to the user by the native
	// program in the terminal. This code is very short lived (~ 1 min) and the
	// native program should periodically fetch and show the most recent code.
	//
	// The purpose of this mechanism is to make sure the user is completing the
	// flow they have actually started in their own terminal. It makes phishing
	// attempts harder, since the target of a phishing attack should not only
	// click through the web UI login flow initiated from a link (which is
	// relatively easy to arrange), but also actively copy-paste an up-to-date
	// code that expires very fast (making "asynchronous" phishing attempts
	// relatively hard to perform).
	//
	// Populated only if the session is still in PENDING state.
	ConfirmationCode string `protobuf:"bytes,9,opt,name=confirmation_code,json=confirmationCode,proto3" json:"confirmation_code,omitempty"`
	// When the confirmation code expires, as duration since when the request to
	// get it completed.
	//
	// It is a relative time (instead of an absolute timestamp) to avoid relying
	// on clock synchronization between the backend and the client machine. Since
	// the code expires pretty fast, even small differences in clocks may cause
	// issues.
	//
	// This value is always sufficiently larger than zero (to give the user some
	// time to use it). The server will prepare a new code in advance if the
	// existing one expires soon. See confirmation_code_refresh below. During such
	// transitions both codes are valid.
	//
	// Populated only if the session is still in PENDING state.
	ConfirmationCodeExpiry *durationpb.Duration `` /* 130-byte string literal not displayed */
	// When the confirmation code will be refreshed (approximately).
	//
	// A "refresh" in this context means GetLoginSession will start returning
	// a new code. It happens somewhat before the previous code expires. That way
	// the user always sees a code that is sufficiently fresh to be copy-pasted
	// into the confirmation web page in a leisurely pace.
	//
	// Populated only if the session is still in PENDING state.
	ConfirmationCodeRefresh *durationpb.Duration `` /* 133-byte string literal not displayed */
	// The OAuth2 authorization code that can be exchanged for OAuth2 tokens.
	//
	// Populated only for sessions in SUCCEEDED state. Getting this code is the
	// goal of LoginSessions service. Knowing this code, an OAuth2 client secret
	// (which is usually hardcoded in the native program code) and the PKCE code
	// verifier secret (which was used to derive `oauth_s256_code_challenge`) is
	// enough to get all OAuth2 tokens.
	//
	// Must not be shared.
	OauthAuthorizationCode string `` /* 130-byte string literal not displayed */
	// An URL that should be used as `redirect_url` parameter when calling the
	// authorization server token endpoint when exchanging the authorization code
	// for tokens.
	//
	// Populated only for sessions in SUCCEEDED state. It is usually a static
	// well-known URL pointing to a page on the login sessions service domain,
	// but it is returned with the session to avoid hardcoding dependencies on
	// implementation details of the login sessions server.
	OauthRedirectUrl string `protobuf:"bytes,13,opt,name=oauth_redirect_url,json=oauthRedirectUrl,proto3" json:"oauth_redirect_url,omitempty"`
	// An optional error message if the login flow failed.
	//
	// Populated only for sessions in FAILED state.
	OauthError string `protobuf:"bytes,14,opt,name=oauth_error,json=oauthError,proto3" json:"oauth_error,omitempty"`
	// contains filtered or unexported fields
}

type LoginSession_State int32

type LoginSessionsClient interface {
	// CreateLoginSession creates a new login session in PENDING state.
	//
	// The returned message contains a new session with auto-generated random `id`
	// and `password`. It's the only reply that has `password` populated. Both
	// `id` and `password` are needed to get the up-to-date state of the session
	// in GetLoginSession.
	//
	// Returns:
	//
	//	INVALID_ARGUMENT: when missing required fields.
	//	PERMISSION_DENIED: when `oauth_client_id` is not recognized or some
	//	    requested scopes are forbidden from use.
	CreateLoginSession(ctx context.Context, in *CreateLoginSessionRequest, opts ...grpc.CallOption) (*LoginSession, error)
	// GetLoginSession returns the current up-to-date state of a login session.
	//
	// The state changes based on interaction with the user in the browser (via
	// a flow launched by visiting `login_flow_url`) and with passage of time.
	//
	// Returns:
	//
	//	INVALID_ARGUMENT: when missing required fields.
	//	NOT_FOUND: if the session is not found, expired long time ago or the
	//	    password doesn't match.
	GetLoginSession(ctx context.Context, in *GetLoginSessionRequest, opts ...grpc.CallOption) (*LoginSession, error)
}

type LoginSessionsServer interface {
	// CreateLoginSession creates a new login session in PENDING state.
	//
	// The returned message contains a new session with auto-generated random `id`
	// and `password`. It's the only reply that has `password` populated. Both
	// `id` and `password` are needed to get the up-to-date state of the session
	// in GetLoginSession.
	//
	// Returns:
	//
	//	INVALID_ARGUMENT: when missing required fields.
	//	PERMISSION_DENIED: when `oauth_client_id` is not recognized or some
	//	    requested scopes are forbidden from use.
	CreateLoginSession(context.Context, *CreateLoginSessionRequest) (*LoginSession, error)
	// GetLoginSession returns the current up-to-date state of a login session.
	//
	// The state changes based on interaction with the user in the browser (via
	// a flow launched by visiting `login_flow_url`) and with passage of time.
	//
	// Returns:
	//
	//	INVALID_ARGUMENT: when missing required fields.
	//	NOT_FOUND: if the session is not found, expired long time ago or the
	//	    password doesn't match.
	GetLoginSession(context.Context, *GetLoginSessionRequest) (*LoginSession, error)
	// contains filtered or unexported methods
}

type UnimplementedLoginSessionsServer struct {
}

type UnsafeLoginSessionsServer interface {
	// contains filtered or unexported methods
}