Adicionar autenticação ao seu aplicativo iOS (Swift)
Este guia assume que você criou um Aplicativo do tipo "Native app" no Console de Administração.
Instalação
Use o seguinte URL para adicionar Logto SDK como uma dependência no Swift Package Manager.
https://github.com/logto-io/swift.git
Desde o Xcode 11, você pode importar diretamente um pacote Swift sem qualquer ferramenta adicional.
Não oferecemos suporte ao Carthage e CocoaPods no momento devido a alguns problemas técnicos.
Carthage
Carthage precisa de um arquivo xcodeproj para compilar, mas swift package generate-xcodeproj irá relatar uma falha, pois estamos usando alvos binários para plugins sociais nativos. Tentaremos encontrar uma solução alternativa mais tarde.
CocoaPods
CocoaPods não suporta dependência local e monorepo, portanto, é difícil criar um .podspec para este repositório.
Integração
Inicializar LogtoClient
Inicie o cliente criando uma instância de LogtoClient com um objeto LogtoConfig.
import Logto
import LogtoClient
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // Ex.: http://localhost:3001
appId: "<your-app-id>"
)
let client = LogtoClient(useConfig: config)
Por padrão, armazenamos credenciais como Token de ID (ID Token) e Token de atualização (Refresh Token) no Keychain. Assim, o usuário não precisa fazer login novamente quando retornar.
Para desativar esse comportamento, defina usingPersistStorage como false:
let config = try? LogtoConfig(
// ...
usingPersistStorage: false
)
Implementar login e logout
Antes de mergulharmos nos detalhes, aqui está uma visão geral rápida da experiência do usuário final. O processo de login pode ser simplificado da seguinte forma:
- Seu aplicativo invoca o método de login.
- O usuário é redirecionado para a página de login do Logto. Para aplicativos nativos, o navegador do sistema é aberto.
- O usuário faz login e é redirecionado de volta para o seu aplicativo (configurado como o URI de redirecionamento).
Sobre o login baseado em redirecionamento
- Este processo de autenticação segue o protocolo OpenID Connect (OIDC), e o Logto aplica medidas de segurança rigorosas para proteger o login do usuário.
- Se você tiver vários aplicativos, pode usar o mesmo provedor de identidade (Logto). Uma vez que o usuário faz login em um aplicativo, o Logto completará automaticamente o processo de login quando o usuário acessar outro aplicativo.
Para saber mais sobre a lógica e os benefícios do login baseado em redirecionamento, veja Experiência de login do Logto explicada.
Configurar URI de redirecionamento
Vamos mudar para a página de detalhes do Aplicativo no Logto Console. Adicione um URI de redirecionamento io.logto://callback e clique em "Salvar alterações".
O URI de redirecionamento no iOS SDK é apenas para uso interno. Não há NECESSIDADE de adicionar um Esquema de URL Personalizado até que um conector solicite.
Login e logout
Antes de chamar .signInWithBrowser(redirectUri:), certifique-se de que você configurou corretamente o URI de redirecionamento no Admin Console.
Você pode usar client.signInWithBrowser(redirectUri:) para fazer login do usuário e client.signOut() para fazer logout do usuário.
Por exemplo, em um aplicativo SwiftUI:
struct ContentView: View {
@State var isAuthenticated: Bool
init() {
isAuthenticated = client.isAuthenticated
}
var body: some View {
VStack {
if isAuthenticated {
Button("Sign Out") {
Task { [self] in
await client.signOut()
isAuthenticated = false
}
}
} else {
Button("Sign In") {
Task { [self] in
do {
try await client.signInWithBrowser(redirectUri: "${
props.redirectUris[0] ?? 'io.logto://callback'
}")
isAuthenticated = true
} catch let error as LogtoClientErrors.SignIn {
// erro ocorreu durante o login
} catch {
// outros erros
}
}
}
}
}
}
}
Ponto de verificação: Teste seu aplicativo
Agora, você pode testar seu aplicativo:
- Execute seu aplicativo, você verá o botão de login.
- Clique no botão de login, o SDK iniciará o processo de login e redirecionará você para a página de login do Logto.
- Após fazer login, você será redirecionado de volta para o seu aplicativo e verá o botão de logout.
- Clique no botão de logout para limpar o armazenamento local e sair.
Obter informações do usuário
Exibir informações do usuário
Para exibir as informações do usuário, você pode usar o método client.getIdTokenClaims(). Por exemplo, em um aplicativo SwiftUI:
struct ContentView: View {
@State var isAuthenticated: Bool
@State var name: String?
init() {
isAuthenticated = client.isAuthenticated
name = try? client.getIdTokenClaims().name
}
var body: some View {
VStack {
if isAuthenticated {
Text("Bem-vindo, \(name)")
} else {
Text("Por favor, faça login")
}
}
}
}
Solicitar reivindicações adicionais
Você pode perceber que algumas informações do usuário estão faltando no objeto retornado de client.getIdTokenClaims(). Isso ocorre porque OAuth 2.0 e OpenID Connect (OIDC) são projetados para seguir o princípio do menor privilégio (PoLP), e o Logto é construído com base nesses padrões.
Por padrão, reivindicações limitadas são retornadas. Se você precisar de mais informações, pode solicitar escopos adicionais para acessar mais reivindicações.
Uma "reivindicação (Claim)" é uma afirmação feita sobre um sujeito; um "escopo (Scope)" é um grupo de reivindicações. No caso atual, uma reivindicação é uma informação sobre o usuário.
Aqui está um exemplo não normativo da relação escopo - reivindicação:
A reivindicação "sub" significa "sujeito (Subject)", que é o identificador único do usuário (ou seja, ID do usuário).
O Logto SDK sempre solicitará três escopos: openid, profile e offline_access.
Para solicitar escopos adicionais, você pode passá-los para o objeto LogtoConfig. Por exemplo:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // Ex.: http://localhost:3001
appId: "<your-app-id>",
scopes: [
UserScope.Email.rawValue,
UserScope.Phone.rawValue,
]
)
Então você pode acessar as reivindicações adicionais no valor de retorno de client.getIdTokenClaims():
let claims = try? client.getIdTokenClaims()
// Agora você pode acessar as reivindicações adicionais `claims.email`, `claims.phone`, etc.
Reivindicações que precisam de solicitações de rede
Para evitar o inchaço do Token de ID (ID token), algumas reivindicações requerem solicitações de rede para serem buscadas. Por exemplo, a reivindicação custom_data não está incluída no objeto do usuário, mesmo que seja solicitada nos escopos. Para acessar essas reivindicações, você pode usar o método client.fetchUserInfo():
let userInfo = try? client.fetchUserInfo()
// Agora você pode acessar a reivindicação `userInfo.custom_data`
Escopos e reivindicações
Logto usa as convenções de escopos e reivindicações do OIDC para definir os escopos e reivindicações para recuperar informações do usuário do Token de ID e do endpoint userinfo do OIDC. Tanto "escopo" quanto "reivindicação" são termos das especificações OAuth 2.0 e OpenID Connect (OIDC).
Aqui está a lista de Escopos (Scopes) suportados e as Reivindicações (Claims) correspondentes:
openid
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| sub | string | O identificador único do usuário | Não |
profile
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| name | string | O nome completo do usuário | Não |
| username | string | O nome de usuário do usuário | Não |
| picture | string | URL da foto de perfil do Usuário Final. Este URL DEVE referir-se a um arquivo de imagem (por exemplo, um arquivo de imagem PNG, JPEG ou GIF), em vez de uma página da Web contendo uma imagem. Note que este URL DEVE referenciar especificamente uma foto de perfil do Usuário Final adequada para exibição ao descrever o Usuário Final, em vez de uma foto arbitrária tirada pelo Usuário Final. | Não |
| created_at | number | Hora em que o Usuário Final foi criado. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z). | Não |
| updated_at | number | Hora em que as informações do Usuário Final foram atualizadas pela última vez. O tempo é representado como o número de milissegundos desde a época Unix (1970-01-01T00:00:00Z). | Não |
Outras reivindicações padrão incluem family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo e locale também serão incluídas no escopo profile sem a necessidade de solicitar o endpoint userinfo. Uma diferença em relação às reivindicações acima é que essas reivindicações só serão retornadas quando seus valores não estiverem vazios, enquanto as reivindicações acima retornarão null se os valores estiverem vazios.
Ao contrário das reivindicações padrão, as reivindicações created_at e updated_at estão usando milissegundos em vez de segundos.
email
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
string | O endereço de email do usuário | Não | |
| email_verified | boolean | Se o endereço de email foi verificado | Não |
phone
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| phone_number | string | O número de telefone do usuário | Não |
| phone_number_verified | boolean | Se o número de telefone foi verificado | Não |
address
Por favor, consulte o OpenID Connect Core 1.0 para os detalhes da reivindicação de endereço.
custom_data
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| custom_data | object | Os dados personalizados do usuário | Sim |
identities
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| identities | object | As identidades vinculadas do usuário | Sim |
| sso_identities | array | As identidades SSO vinculadas do usuário | Sim |
urn:logto:scope:organizations
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| organizations | string[] | Os IDs das organizações às quais o usuário pertence | Não |
| organization_data | object[] | Os dados das organizações às quais o usuário pertence | Sim |
urn:logto:scope:organization_roles
| Nome da Reivindicação | Tipo | Descrição | Precisa de userinfo? |
|---|---|---|---|
| organization_roles | string[] | Os papéis da organização aos quais o usuário pertence com o formato <organization_id>:<role_name> | Não |
Considerando o desempenho e o tamanho dos dados, se "Precisa de userinfo?" for "Sim", isso significa que a reivindicação não aparecerá no Token de ID, mas será retornada na resposta do endpoint userinfo.
Recursos de API
Recomendamos ler 🔐 Controle de Acesso Baseado em Papel (RBAC) primeiro para entender os conceitos básicos do RBAC do Logto e como configurar corretamente os recursos de API.
Configurar cliente Logto
Depois de configurar os recursos de API, você pode adicioná-los ao configurar o Logto em seu aplicativo:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // Exemplo: http://localhost:3001
appId: "<your-app-id>",
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"], // Adicionar recursos de API
)
let client = LogtoClient(useConfig: config)
Cada recurso de API tem suas próprias permissões (escopos).
Por exemplo, o recurso https://shopping.your-app.com/api tem as permissões shopping:read e shopping:write, e o recurso https://store.your-app.com/api tem as permissões store:read e store:write.
Para solicitar essas permissões, você pode adicioná-las ao configurar o Logto em seu aplicativo:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>",
appId: "<your-app-id>",
scopes: ["shopping:read", "shopping:write", "store:read", "store:write"],
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
)
let client = LogtoClient(useConfig: config)
Você pode notar que os escopos são definidos separadamente dos recursos de API. Isso ocorre porque Resource Indicators for OAuth 2.0 especifica que os escopos finais para a solicitação serão o produto cartesiano de todos os escopos em todos os serviços de destino.
Assim, no caso acima, os escopos podem ser simplificados a partir da definição no Logto, ambos os recursos de API podem ter escopos read e write sem o prefixo. Então, na configuração do Logto:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>",
appId: "<your-app-id>",
scopes: ["read", "write"],
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
)
let client = LogtoClient(useConfig: config)
Para cada recurso de API, ele solicitará os escopos read e write.
Não há problema em solicitar escopos que não estão definidos nos recursos de API. Por exemplo, você pode solicitar o escopo email mesmo que os recursos de API não tenham o escopo email disponível. Escopos indisponíveis serão ignorados com segurança.
Após o login bem-sucedido, o Logto emitirá os escopos apropriados para os recursos de API de acordo com os papéis do usuário.
Buscar token de acesso para o recurso de API
Para buscar o token de acesso para um recurso de API específico, você pode usar o método getAccessToken:
let accessToken = try await client.getAccessToken(for: "https://shopping.your-app.com/api")
Este método retornará um token de acesso JWT que pode ser usado para acessar o recurso de API quando o usuário tiver as permissões relacionadas. Se o token de acesso em cache atual tiver expirado, este método tentará automaticamente usar um token de atualização para obter um novo token de acesso.
Anexar token de acesso aos cabeçalhos de solicitação
Coloque o token no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN), e você estará pronto para prosseguir.
O fluxo de integração do Bearer Token pode variar com base no framework ou solicitante que você está usando. Escolha sua própria maneira de aplicar o cabeçalho de solicitação Authorization.
await LogtoRequest.get(
useSession: session,
endpoint: userInfoEndpoint,
headers: ["Authorization": "Bearer \(accessToken)"]
)