SFAuthorization Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSObject (NSObject)
Framework
/Library/Frameworks/SecurityFoundation.framework
Availability
Available in OS X v10.3 and later
Companion guide
Authorization Services Programming Guide
Declared in
SFAuthorization.h

Overview

The SFAuthorization class allows you to restrict a user’s access to particular features in your Mac app or daemon.

The SFAuthorization class is an Objective-C interface for some of the functions in the Authorization Services API. You can use the authorizationRef method to obtain an authorization reference, used in other calls to Authorization Services functions. The Authorization Services API is documented in Authorization Services C Reference.

Tasks

Allocating and Initializing an Authorization Object

Obtaining an Authorization Reference

Authorizing Rights

Preventing Credentials from Being Shared

Class Methods

authorization

Returns an authorization object initialized with a default environment, flags, and rights.

+ (id)authorization
Return Value

The authorization object.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFAuthorization.h

authorizationWithFlags:rights:environment:

Returns an authorization object initialized with the specified flags, rights and environment.

+ (id)authorizationWithFlags:(AuthorizationFlags)flags rights:(const AuthorizationRights *)rights environment:(const AuthorizationEnvironment *)environment
Parameters
flags

A bit mask for specifying authorization options. Use the following option sets:

  • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

  • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

  • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

rights

A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

environment

Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security.framework/Headers/AuthorizationTags.h. The data passed in this parameter is not stored in the authorization reference; it is used only during authorization. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

Return Value

The authorization object.

Discussion

Normally, such initialization is not required, as you pass in flags, rights, and environmental data when you request authorization.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFAuthorization.h

Instance Methods

authorizationRef

Returns the authorization reference for this object.

- (AuthorizationRef)authorizationRef
Return Value

The authorization reference.

Discussion

You can use the authorization reference in calls to Authorization Services functions.

For additional information see Authorization Services C Reference.

Availability
  • Available in OS X v10.3 and later.
Declared In
SFAuthorization.h

init

Initializes an authorization object with default environment, flags, and rights.

- (id)init
Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorization.h

initWithFlags:rights:environment:

Initializes an authorization object with the specified flags, rights, and environment.

- (id)initWithFlags:(AuthorizationFlags)flags rights:(const AuthorizationRights *)rights environment:(const AuthorizationEnvironment *)environment
Parameters
flags

A bit mask for specifying authorization options. Use the following option sets:

  • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

  • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

  • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

rights

A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

environment

Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security/AuthorizationTags.h. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

Return Value

The authorization object.

Discussion

You can use this method to initialize an authorization object. Normally, such initialization is not required, as you pass in flags, rights, and environmental data when you request authorization.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFAuthorization.h

invalidateCredentials

Prevents any rights that were obtained by this object from being preserved.

- (void)invalidateCredentials
Discussion

This method effectively ensures that authorizations are not shared.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFAuthorization.h

obtainWithRight:flags:error:

Authorizes and preauthorizes one specific right.

- (BOOL)obtainWithRight:(AuthorizationString)rightName flags:(AuthorizationFlags)flags error:(NSError **)error
Parameters
rightName

The name of an authorization right.

flags

A bit mask for specifying authorization options. See obtainWithRights:flags:environment:authorizedRights:error: for details about possible flag values.

error

On completion, the result code returned by the method. See “Result Codes” in Authorization Services C Reference.

Return Value

YES if operation completes successfully.

Discussion

Use this method to authorize or preauthorize a single right.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFAuthorization.h

obtainWithRights:flags:environment:authorizedRights:error:

Authorizes and preauthorizes rights to access a privileged operation and returns the granted rights.

- (BOOL)obtainWithRights:(const AuthorizationRights *)rights flags:(AuthorizationFlags)flags environment:(const AuthorizationEnvironment *)environment authorizedRights:(AuthorizationRights **)authorizedRights error:(NSError **)error;
Parameters
rights

A pointer to a set of authorization rights you create. Pass NULL if the application requires no rights at this time.

flags

A bit mask for specifying authorization options. Use the following option sets:

  • Pass the constant kAuthorizationFlagDefaults if no options are necessary.

  • Specify the kAuthorizationFlagExtendRights mask to request rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPartialRights and kAuthorizationFlagExtendRights masks to request partial rights. You can also specify the kAuthorizationFlagInteractionAllowed mask to allow user interaction.

  • Specify the kAuthorizationFlagPreAuthorize and kAuthorizationFlagExtendRights masks to preauthorize rights.

  • Specify the kAuthorizationFlagDestroyRights mask to prevent the Security framework from preserving the rights obtained during this call.

environment

Data used when authorizing or preauthorizing rights. In OS X v10.3 and later, you can pass icon or prompt data to be used in the authentication dialog box. Possible values for this parameter are listed in Security/AuthorizationTags.h. If you are not passing any data in this parameter, pass the constant kAuthorizationEmptyEnvironment.

authorizedRights

A pointer to a newly allocated AuthorizationRights structure. On return, this structure contains the rights granted by the Security framework. If you do not require this information, pass NULL. If you specify the kAuthorizationFlagPreAuthorize mask in the flags parameter, the method returns all the requested rights, including those not granted, but the flags of the rights that could not be preauthorized include the kAuthorizationFlagCanNotPreAuthorize bit.

Free the memory associated with this set of rights by calling the Authorization Services function AuthorizationFreeItemSet.

error

On completion, the result code returned by the method. See “Result Codes” in Authorization Services C Reference.

Return Value

YES if operation completes successfully.

Discussion

There are three main reasons to use this method. The first reason is to preauthorize rights by specifying the kAuthorizationFlagPreAuthorize, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options. Preauthorization is most useful when a right has a zero timeout. For example, you can preauthorize in the application and if it succeeds, call the helper tool and request authorization. This eliminates calling the helper tool if the Security framework cannot later authorize the specified rights.

The second reason to use this method is to authorize rights before performing a privileged operation by specifying the kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options.

The third reason to use this method is to authorize partial rights. By specifying the kAuthorizationFlagPartialRights, kAuthorizationFlagInteractionAllowed, and kAuthorizationFlagExtendRights masks as authorization options, the Security framework grants all rights it can authorize. On return, the authorized set contains all the rights.

If you do not specify the kAuthorizationFlagPartialRights mask and the Security framework denies at least one right, then the method returns NO and the error parameter returns errAuthorizationDenied.

If you do not specify the kAuthorizationFlagInteractionAllowed mask and the Security framework requires user interaction, then the method returns NO and the error parameter returns errAuthorizationInteractionNotAllowed.

If you specify the kAuthorizationFlagInteractionAllowed mask and the user cancels the authentication process, then the method returns NO and the error parameter returns errAuthorizationCanceled.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
SFAuthorization.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-19)

Did this document help you? Yes It's good, but... Not helpful...