PushCredential

public struct PushCredential : Codable, Identifiable, @unchecked Sendable, CustomStringConvertible

Represents a Push credential for push authentication.

A Push credential contains all the information needed to register a device for push notifications and to authenticate using push challenges. This model follows the PingAM (ForgeRock) push authentication protocol.

Credential Sources

Push credentials are typically created by:

  • Scanning a QR code containing a pushauth:// or mfauth:// URI
  • Receiving credential information from a server API
  • Importing from backup or migration

Security Considerations

  • The sharedSecret is used for cryptographic operations and must be protected
  • Credentials can be locked based on policy violations
  • All credential data should be stored securely in the Keychain

Usage Example

// From QR code
let credential = try await PushCredential.fromUri(qrCodeUri)

// Manual creation
let credential = PushCredential(
    issuer: "MyCompany",
    accountName: "user@example.com",
    serverEndpoint: "https://am.example.com/push",
    sharedSecret: "base64EncodedSecret"
)

Properties

  • id

    Unique identifier for the credential (local ID).

    Declaration

    Swift

    public let id: String

  • User identifier on the server.

    Declaration

    Swift

    public let userId: String?

  • Server-side device identifier. If not provided during initialization, defaults to the credential ID.

    Declaration

    Swift

    public let resourceId: String

  • The name of the issuer for this credential.

    Declaration

    Swift

    public let issuer: String

  • The name of the issuer for this credential, editable by the user.

    Declaration

    Swift

    public var displayIssuer: String

  • The account name associated with this credential.

    Declaration

    Swift

    public let accountName: String

  • The account name associated with this credential, editable by the user.

    Declaration

    Swift

    public var displayAccountName: String

  • The endpoint where authentication responses should be sent. This is the base URL for push operations (registration, authentication, update).

    Declaration

    Swift

    public let serverEndpoint: String

  • The timestamp when this credential was created.

    Declaration

    Swift

    public let createdAt: Date

  • Optional URL for the issuer’s logo or image.

    Declaration

    Swift

    public let imageURL: String?

  • Optional background color for the credential (hex format).

    Declaration

    Swift

    public let backgroundColor: String?

  • Optional Authenticator Policies in a JSON String format for the credential.

    Declaration

    Swift

    public let policies: String?

  • Optional name of the Policy locking the credential.

    Declaration

    Swift

    public var lockingPolicy: String?

  • Indicates whether the credential is locked.

    Declaration

    Swift

    public var isLocked: Bool

  • The platform for which this credential is intended (e.g., PING_AM).

    Declaration

    Swift

    public let platform: PushPlatform

  • Optional additional data associated with this credential. Note: This is not directly encoded/decoded due to type erasure limitations.

    Declaration

    Swift

    public var additionalData: [String : Any]?

Computed Properties

  • Returns the registration endpoint for this credential. This is used to register the device with the PingAM servers.

    Declaration

    Swift

    public var registrationEndpoint: String { get }

  • Returns the authentication endpoint for this credential. This is used to authenticate the user via push notification with the PingAM servers.

    Declaration

    Swift

    public var authenticationEndpoint: String { get }

  • Returns the update endpoint for this credential. This is used to refresh or update the device token with the PingAM servers.

    Declaration

    Swift

    public var updateEndpoint: String { get }

CustomStringConvertible

  • Declaration

    Swift

    public var description: String { get }

Initializers

  • Creates a new Push credential.

    Declaration

    Swift

    public init(
    id: String = UUID().uuidString,
    userId: String? = nil,
    resourceId: String? = nil,
    issuer: String,
    displayIssuer: String? = nil,
    accountName: String,
    displayAccountName: String? = nil,
    serverEndpoint: String,
    sharedSecret: String,
    createdAt: Date = Date(),
    imageURL: String? = nil,
    backgroundColor: String? = nil,
    policies: String? = nil,
    lockingPolicy: String? = nil,
    isLocked: Bool = false,
    platform: PushPlatform = .pingAM,
    additionalData: [String: Any]? = nil
)

    Parameters

    id

    Unique identifier for the credential. Defaults to a new UUID.
    userId

    User identifier on the server.
    resourceId

    Server-side device identifier. Defaults to id if not provided.
    issuer

    The name of the issuer for this credential.
    displayIssuer

    The display name of the issuer, editable by the user.
    accountName

    The account name associated with this credential.
    displayAccountName

    The display account name, editable by the user.
    serverEndpoint

    The endpoint where authentication responses should be sent.
    sharedSecret

    The secret key used for cryptographic operations.
    createdAt

    The creation timestamp. Defaults to current date.
    imageURL

    Optional URL for the issuer’s image.
    backgroundColor

    Optional background color.
    policies

    Optional policies in JSON format.
    lockingPolicy

    Optional locking policy name.
    isLocked

    Whether the credential is locked. Defaults to false.
    platform

    The platform for this credential. Defaults to PING_AM.
    additionalData

    Optional additional data.

Factory Methods

  • fromUri(_:) Asynchronous

    Creates a Push credential from a URI string.

    This method parses a pushauth:// or mfauth:// URI (typically from a QR code) and creates a credential with the extracted information.

    Throws

    PushError.invalidUri if the URI is malformed.

    Example

    let uri = "pushauth://push/MyCompany:user@example.com?r=https://...&s=secret..."
let credential = try await PushCredential.fromUri(uri)

    Declaration

    Swift

    public static func fromUri(_ uri: String) async throws -> PushCredential

    Parameters

    uri

    The pushauth:// or mfauth:// URI string to parse.

    Return Value

    A new PushCredential instance.

  • toUri() Asynchronous

    Converts this credential to a URI string.

    This method creates a pushauth:// or mfauth:// URI that can be used to transfer or backup the credential (e.g., as a QR code).

    Throws

    PushError.uriFormatting if formatting fails.

    Example

    let uri = try await credential.toUri()
// Use uri to generate QR code for backup

    Declaration

    Swift

    public func toUri() async throws -> String

    Return Value

    A URI string representation of this credential.

Policy Methods

  • Lock this credential due to policy violations.

    Locked credentials cannot be used for authentication until they are unlocked. This is typically enforced by policy evaluators checking for jailbreak, device compromise, or other security violations.

    Declaration

    Swift

    public mutating func lockCredential(policyName: String)

    Parameters

    policyName

    The name of the policy that caused the lock.

  • Unlock this credential.

    This removes any locking policy information and allows the credential to be used for authentication again.

    Declaration

    Swift

    public mutating func unlockCredential()

Codable

  • Declaration

    Swift

    public init(from decoder: Decoder) throws

  • Declaration

    Swift

    public func encode(to encoder: Encoder) throws